---
title: "Create a new Secret Value"
method: POST
path: "/v1/secrets/{agentId}/secret-value"
tags: ["Secrets"]
---

# Create a new Secret Value

`POST /v1/secrets/{agentId}/secret-value`

Creates a new secret value, which is encrypted in transit using the certificate of the provided Agent, then decrypted by the Agent and stored in plain-text within the Customer vault.

## Path parameters

- `agentId` string, required

## Query parameters

- `projectId` string, uuid

## Request body

- UnencryptedSecretRequest
  - `secret` SecretValueRequest, required
    - `key` string — The optional top-level property to use inside the (json-valued) secret. This is used to build a reference to the secret being stored so it can be used in pipelines. If you are storing a single scalar secret, this can be the top-level property of the value being stored. Note that nested properties such as "parent.child" cannot be referenced here. If you are storing a complex JSON object and want to resolve the whole object, this should not be provided to allow the resolver to return the whole object from the secret.
    - `name` string, required — The name of the secret to store. This is an identifier for the secret and should be unique in the project.
    - `type` string — The type of the secret to store, such as PASSWORD or OAUTH_CLIENT_CREDENTIALS.
    - `value` unknown

## Response `201`

Created

- ResolverSecretReferenceResponse
  - `resolver_ref` string
  - `vaultSecretName` string

## Other responses

- `400` — Wrong request parameters used
- `403` — Unauthorized
- `409` — A secret with that target name already exists in the vault location
- `500` — Unexpected error occurred
- `504` — Gateway timeout

---

[API](https://skmtc.net/maia/apis/maia-public-rest-api.md) · [All operations](https://skmtc.net/maia/apis/maia-public-rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/maia/maia-public-rest-api/versions/6239825f68eb/schema)