---
title: "Create a secret"
method: POST
path: "/secrets"
tags: ["secrets"]
---

# Create a secret

`POST /secrets`

Creates Dagu-managed secret metadata in global scope or a named workspace and optionally writes an initial value. Plaintext values are write-only.

## Query parameters

- `remoteNode` string

## Request body

- CreateSecretRequest
  - `workspace` string — Secret scope for management. Use global for workspace-less secrets or a workspace name. Omit for global.
  - `ref` string, required — Secret ref used from DAG YAML, for example prod/db-password.
  - `description` string
  - `providerType` 'dagu-managed', required
  - `value` string — Initial Dagu-managed value. Write-only; never returned by the API.

## Response `201`

Secret created

- SecretResponse
  - `id` string, required
  - `workspace` string, required — global for workspace-less secrets, otherwise the workspace name.
  - `ref` string, required — Secret ref used from DAG YAML, for example prod/db-password.
  - `description` string
  - `providerType` 'dagu-managed' | 'vault' | 'kubernetes' | 'gcp' | 'aws' | 'azure' | 'alibaba', required
  - `providerConnectionId` string
  - `providerRef` string
  - `providerRefFingerprint` string
  - `currentVersion` integer, required
  - `status` 'active' | 'disabled', required
  - `hasValue` boolean, required
  - `createdAt` string, date-time, required
  - `updatedAt` string, date-time, required
  - `lastCheckedAt` string, date-time
  - `lastResolvedAt` string, date-time
  - `lastRotatedAt` string, date-time

## Other responses

- `400` — Invalid request
- `401` — Not authenticated
- `403` — Not authorized
- `409` — Secret already exists
- `default` — Generic error response

## Changes

- **2026-07-25** (v1) `5a824a778eac` — 1 warning
  - added the new `alibaba` enum value to the `providerType` response property for the response status `201`
- **2026-07-25** (v1) `210385768f1a` — 2 warning, 2 info
  - added the new `azure` enum value to the `providerType` response property for the response status `201`
  - added the new `gcp` enum value to the `providerType` response property for the response status `201`
  - removed the `azure-key-vault` enum value from the `providerType` response property for the response status `201`
  - removed the `gcp-secret-manager` enum value from the `providerType` response property for the response status `201`
- **2026-07-25** (v1) `8ac8440c17ff` — 1 warning, 1 info
  - added the new `aws` enum value to the `providerType` response property for the response status `201`
  - removed the `aws-secrets-manager` enum value from the `providerType` response property for the response status `201`
- **2026-07-23** (v1) `75b8e91aaf57` — 15 warning
  - added the new `conflict` enum value to the `code` response property for the response status `400`
  - added the new `conflict` enum value to the `code` response property for the response status `401`
  - added the new `conflict` enum value to the `code` response property for the response status `403`
  - added the new `conflict` enum value to the `code` response property for the response status `409`
  - …11 more
- …earlier changes not shown

[Full history](https://skmtc.dev/dagucloud/apis/dagu/changes/secrets/post.md)

---

[API](https://skmtc.dev/dagucloud/apis/dagu.md) · [All operations](https://skmtc.dev/dagucloud/apis/dagu/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/dagucloud/dagu/revisions/9fcb8e054188/schema)