---
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`

## Request

- Base URL: `https://eu1.api.matillion.com/dpc`
- URL: `https://eu1.api.matillion.com/dpc/v1/secrets/{agentId}/secret-value`
- Auth: HTTP bearer

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.dev/maia/apis/maia-public-rest-api.md) - [All operations](https://skmtc.dev/maia/apis/maia-public-rest-api/llms.txt) - [OpenAPI document](https://skmtc.dev/maia/apis/maia-public-rest-api/revisions/6239825f68eb?raw)