coder/docs/reference/api/secrets.md at 2ee96f82f947a14861956c18fdd957a439b8a671

mirror of https://github.com/coder/coder.git synced 2026-10-16 14:48:56 +08:00

Files

T

dylanhuff-at-coder 4875ae218a feat: enforce user secret file policy (#28518 )

Adds the deployment option `--user-secrets-disable-file-path` /
`CODER_USER_SECRETS_DISABLE_FILE_PATH` / `userSecretsDisableFilePath`
(default `false`). When it is set, the create and batch-create
user-secret endpoints reject requests with a non-empty file path, and
PATCH validates the post-update state under a `SELECT ... FOR UPDATE`
row lock, rejecting a new or changed file path as well as enabled states
that would have no effective delivery target. Legacy stored paths are
preserved, so users can still edit, disable, clear the path, or migrate
the secret to env delivery.

This is PR 1 of a 4-PR stack; follow-ups cover manifest filtering, the
dashboard, and CLI/docs.

Refs #27488

Reviewed and updated by Coder Agents on behalf of @dylanhuff-at-coder.

2026-09-02 09:21:36 -07:00

17 KiB

Generated

Raw Blame History

title

title
Secrets

List user secrets

Code samples

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

GET /api/v2/users/{user}/secrets

Parameters

Name	In	Type	Required	Description
`user`	path	string	true	User ID, username, or me

Example responses

200 Response

[
  {
    "created_at": "2019-08-24T14:15:22Z",
    "description": "string",
    "enabled": true,
    "env_name": "string",
    "file_path": "string",
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "name": "string",
    "updated_at": "2019-08-24T14:15:22Z"
  }
]

Responses

Status	Meaning	Description	Schema
200	OK	OK	array of codersdk.UserSecret

Response Schema

Status Code 200

Name	Type	Required	Description
`[array item]`	array	false
`» created_at`	string(date-time)	false
`» description`	string	false
`» enabled`	boolean	false	Enabled controls whether the secret is injected into workspaces. Disabled secrets remain visible and editable, but are not added to the agent manifest, so they are not exposed as environment variables or written to secret files.
`» env_name`	string	false
`» file_path`	string	false
`» id`	string(uuid)	false
`» name`	string	false
`» updated_at`	string(date-time)	false

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

Create a new user secret

Code samples

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

POST /api/v2/users/{user}/secrets

Body parameter

{
  "description": "string",
  "enabled": true,
  "env_name": "string",
  "file_path": "string",
  "name": "string",
  "value": "string"
}

Parameters

Name	In	Type	Required	Description
`user`	path	string	true	User ID, username, or me
`body`	body	codersdk.CreateUserSecretRequest	true	Create secret request

Example responses

201 Response

{
  "created_at": "2019-08-24T14:15:22Z",
  "description": "string",
  "enabled": true,
  "env_name": "string",
  "file_path": "string",
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "name": "string",
  "updated_at": "2019-08-24T14:15:22Z"
}

Responses

Status	Meaning	Description	Schema
201	Created	Created	codersdk.UserSecret
400	Bad Request	Bad Request	codersdk.Response
409	Conflict	Conflict	codersdk.Response

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

Import user secrets from a file

Code samples

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

POST /api/v2/users/{user}/secrets/batch

Body parameter

{
  "content": "string",
  "format": "env"
}

Parameters

Name	In	Type	Required	Description
`user`	path	string	true	User ID, username, or me
`body`	body	codersdk.ImportUserSecretsRequest	true	Import secrets request

Example responses

201 Response

[
  {
    "created_at": "2019-08-24T14:15:22Z",
    "description": "string",
    "enabled": true,
    "env_name": "string",
    "file_path": "string",
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "name": "string",
    "updated_at": "2019-08-24T14:15:22Z"
  }
]

Responses

Status	Meaning	Description	Schema
201	Created	Created	array of codersdk.UserSecret
400	Bad Request	Bad Request	codersdk.Response
409	Conflict	Conflict	codersdk.Response
413	Payload Too Large	Request body exceeds 8 MiB	codersdk.Response

Response Schema

Status Code 201

Name	Type	Required	Description
`[array item]`	array	false
`» created_at`	string(date-time)	false
`» description`	string	false
`» enabled`	boolean	false	Enabled controls whether the secret is injected into workspaces. Disabled secrets remain visible and editable, but are not added to the agent manifest, so they are not exposed as environment variables or written to secret files.
`» env_name`	string	false
`» file_path`	string	false
`» id`	string(uuid)	false
`» name`	string	false
`» updated_at`	string(date-time)	false

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

Get a user secret by name

Code samples

# Example request using curl
curl -X GET http://coder-server:8080/api/v2/users/{user}/secrets/{name} \
  -H 'Accept: application/json' \
  -H 'Coder-Session-Token: API_KEY'

GET /api/v2/users/{user}/secrets/{name}

Parameters

Name	In	Type	Required	Description
`user`	path	string	true	User ID, username, or me
`name`	path	string	true	Secret name

Example responses

200 Response

{
  "created_at": "2019-08-24T14:15:22Z",
  "description": "string",
  "enabled": true,
  "env_name": "string",
  "file_path": "string",
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "name": "string",
  "updated_at": "2019-08-24T14:15:22Z"
}

Responses

Status	Meaning	Description	Schema
200	OK	OK	codersdk.UserSecret

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

Delete a user secret

Code samples

# Example request using curl
curl -X DELETE http://coder-server:8080/api/v2/users/{user}/secrets/{name} \
  -H 'Coder-Session-Token: API_KEY'

DELETE /api/v2/users/{user}/secrets/{name}

Parameters

Name	In	Type	Required	Description
`user`	path	string	true	User ID, username, or me
`name`	path	string	true	Secret name

Responses

Status	Meaning	Description	Schema
204	No Content	No Content

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

Update a user secret

Code samples

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

PATCH /api/v2/users/{user}/secrets/{name}

Body parameter

{
  "description": "string",
  "enabled": true,
  "env_name": "string",
  "file_path": "string",
  "value": "string"
}

Parameters

Name	In	Type	Required	Description
`user`	path	string	true	User ID, username, or me
`name`	path	string	true	Secret name
`body`	body	codersdk.UpdateUserSecretRequest	true	Update secret request

Example responses

200 Response

{
  "created_at": "2019-08-24T14:15:22Z",
  "description": "string",
  "enabled": true,
  "env_name": "string",
  "file_path": "string",
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "name": "string",
  "updated_at": "2019-08-24T14:15:22Z"
}

Responses

Status	Meaning	Description	Schema
200	OK	OK	codersdk.UserSecret
400	Bad Request	Bad Request	codersdk.Response
409	Conflict	Conflict	codersdk.Response

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

17 KiB Generated Raw Blame History

List user secrets

Code samples

Parameters

Example responses

Responses

Response Schema

Create a new user secret

Code samples

Parameters

Example responses

Responses

Import user secrets from a file

Code samples

Parameters

Example responses

Responses

Response Schema

Get a user secret by name

Code samples

Parameters

Example responses

Responses

Delete a user secret

Code samples

Parameters

Responses

Update a user secret

Code samples

Parameters

Example responses

Responses

17 KiB

Generated

Raw Blame History