mirror of
https://github.com/coder/coder.git
synced 2026-09-24 15:04:27 +08:00
dylanhuff-at-coder
d5a3963167
Adds `POST /api/v2/users/{user}/secrets/batch` and
`codersdk.Client.ImportUserSecrets` to import env, JSON, or YAML secrets
atomically. The endpoint validates each entry, rolls back the full batch
on conflicts or limits, omits secret values from responses and audit
logs, and imports keys that cannot be injected as environment variables
with an empty `env_name`.
Part of the [PLAT-240 bulk secret import
stack](https://linear.app/codercom/issue/PLAT-240). Reviewed and updated
by Coder Agents on behalf of @dylanhuff-at-coder.
321 lines
11 KiB
Markdown
Generated
321 lines
11 KiB
Markdown
Generated
# Secrets
|
|
|
|
## List user secrets
|
|
|
|
### Code samples
|
|
|
|
```sh
|
|
# 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
|
|
|
|
```json
|
|
[
|
|
{
|
|
"created_at": "2019-08-24T14:15:22Z",
|
|
"description": "string",
|
|
"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](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | array of [codersdk.UserSecret](schemas.md#codersdkusersecret) |
|
|
|
|
<h3 id="list-user-secrets-responseschema">Response Schema</h3>
|
|
|
|
Status Code **200**
|
|
|
|
| Name | Type | Required | Restrictions | Description |
|
|
|-----------------|-------------------|----------|--------------|-------------|
|
|
| `[array item]` | array | false | | |
|
|
| `» created_at` | string(date-time) | false | | |
|
|
| `» description` | string | false | | |
|
|
| `» 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](authentication.md).
|
|
|
|
## Create a new user secret
|
|
|
|
### Code samples
|
|
|
|
```sh
|
|
# 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
|
|
|
|
```json
|
|
{
|
|
"description": "string",
|
|
"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](schemas.md#codersdkcreateusersecretrequest) | true | Create secret request |
|
|
|
|
### Example responses
|
|
|
|
> 201 Response
|
|
|
|
```json
|
|
{
|
|
"created_at": "2019-08-24T14:15:22Z",
|
|
"description": "string",
|
|
"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](https://tools.ietf.org/html/rfc7231#section-6.3.2) | Created | [codersdk.UserSecret](schemas.md#codersdkusersecret) |
|
|
|
|
To perform this operation, you must be authenticated. [Learn more](authentication.md).
|
|
|
|
## Import user secrets from a file
|
|
|
|
### Code samples
|
|
|
|
```sh
|
|
# 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
|
|
|
|
```json
|
|
{
|
|
"content": "string",
|
|
"format": "env"
|
|
}
|
|
```
|
|
|
|
### Parameters
|
|
|
|
| Name | In | Type | Required | Description |
|
|
|--------|------|----------------------------------------------------------------------------------|----------|--------------------------|
|
|
| `user` | path | string | true | User ID, username, or me |
|
|
| `body` | body | [codersdk.ImportUserSecretsRequest](schemas.md#codersdkimportusersecretsrequest) | true | Import secrets request |
|
|
|
|
### Example responses
|
|
|
|
> 201 Response
|
|
|
|
```json
|
|
[
|
|
{
|
|
"created_at": "2019-08-24T14:15:22Z",
|
|
"description": "string",
|
|
"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](https://tools.ietf.org/html/rfc7231#section-6.3.2) | Created | array of [codersdk.UserSecret](schemas.md#codersdkusersecret) |
|
|
| 400 | [Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1) | Bad Request | [codersdk.Response](schemas.md#codersdkresponse) |
|
|
| 409 | [Conflict](https://tools.ietf.org/html/rfc7231#section-6.5.8) | Conflict | [codersdk.Response](schemas.md#codersdkresponse) |
|
|
| 413 | [Payload Too Large](https://tools.ietf.org/html/rfc7231#section-6.5.11) | Request Entity Too Large | [codersdk.Response](schemas.md#codersdkresponse) |
|
|
|
|
<h3 id="import-user-secrets-from-a-file-responseschema">Response Schema</h3>
|
|
|
|
Status Code **201**
|
|
|
|
| Name | Type | Required | Restrictions | Description |
|
|
|-----------------|-------------------|----------|--------------|-------------|
|
|
| `[array item]` | array | false | | |
|
|
| `» created_at` | string(date-time) | false | | |
|
|
| `» description` | string | false | | |
|
|
| `» 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](authentication.md).
|
|
|
|
## Get a user secret by name
|
|
|
|
### Code samples
|
|
|
|
```sh
|
|
# 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
|
|
|
|
```json
|
|
{
|
|
"created_at": "2019-08-24T14:15:22Z",
|
|
"description": "string",
|
|
"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](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | [codersdk.UserSecret](schemas.md#codersdkusersecret) |
|
|
|
|
To perform this operation, you must be authenticated. [Learn more](authentication.md).
|
|
|
|
## Delete a user secret
|
|
|
|
### Code samples
|
|
|
|
```sh
|
|
# 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](https://tools.ietf.org/html/rfc7231#section-6.3.5) | No Content | |
|
|
|
|
To perform this operation, you must be authenticated. [Learn more](authentication.md).
|
|
|
|
## Update a user secret
|
|
|
|
### Code samples
|
|
|
|
```sh
|
|
# 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
|
|
|
|
```json
|
|
{
|
|
"description": "string",
|
|
"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](schemas.md#codersdkupdateusersecretrequest) | true | Update secret request |
|
|
|
|
### Example responses
|
|
|
|
> 200 Response
|
|
|
|
```json
|
|
{
|
|
"created_at": "2019-08-24T14:15:22Z",
|
|
"description": "string",
|
|
"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](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | [codersdk.UserSecret](schemas.md#codersdkusersecret) |
|
|
|
|
To perform this operation, you must be authenticated. [Learn more](authentication.md).
|