---
title: "Create Secret"
method: POST
path: "/secrets/"
tags: ["Secrets"]
---

# Create Secret

`POST /secrets/`

## Request body

- CreateSecretDTO
  - `slug` string, nullable
  - `header` Header, required
    - `name` string, nullable
    - `description` string, nullable
  - `secret` SecretDTO, required — Create-time secret payload. Required credential fields must be present.
    - `kind` 'provider_key' | 'custom_provider' | 'sso_provider' | 'webhook_provider' | 'custom_secret', required
    - `data` union, required
      - StandardProviderDTO
        - `kind` 'openai' | 'cohere' | 'anyscale' | 'deepinfra' | 'alephalpha' | 'groq' | 'minimax' | 'mistral' | 'mistralai' | 'anthropic' | 'perplexityai' | 'together_ai' | 'openrouter' | 'gemini', required
        - `provider` StandardProviderSettingsDTO, required
          - `key` string, nullable
        - `models` CustomModelSettingsDTO[], nullable
          - `slug` string, required
          - `extras` object, nullable
        - `harnesses` string[], nullable
      - CustomProviderDTO
        - `kind` 'custom' | 'azure' | 'bedrock' | 'sagemaker' | 'vertex_ai' | 'openai' | 'cohere' | 'anyscale' | 'deepinfra' | 'alephalpha' | 'groq' | 'minimax' | 'mistral' | 'mistralai' | 'anthropic' | 'perplexityai' | 'together_ai' | 'openrouter' | 'gemini', required
        - `provider` CustomProviderSettingsDTO, required
          - `url` string, nullable
          - `version` string, nullable
          - `key` string, nullable
          - `extras` object, nullable
        - `models` CustomModelSettingsDTO[], required
          - `slug` string, required
          - `extras` object, nullable
        - `harnesses` string[], nullable
        - `provider_slug` string, nullable
        - `model_keys` string[], nullable
      - SSOProviderDTO
        - `provider` SSOProviderSettingsDTO, required
          - `client_id` string, required
          - `client_secret` string, nullable
          - `issuer_url` string, required
          - `scopes` string[], required
          - `extra` object
      - WebhookProviderDTO
        - `provider` WebhookProviderSettingsDTO, required
          - `key` string, nullable
      - CustomSecretDTO
        - `secret` CustomSecretSettingsDTO, required
          - `format` 'text' | 'json', required
          - `content` union
            - string
            - object
  - `write_only` boolean

## Response `200`

Successful Response

- PublicSecretResponseDTO — Caller-facing representation after grant-aware value projection.
  - `slug` string, nullable
  - `id` string, uuid, nullable
  - `kind` 'provider_key' | 'custom_provider' | 'sso_provider' | 'webhook_provider' | 'custom_secret', required
  - `data` union, required
    - StandardProviderDTO
      - `kind` 'openai' | 'cohere' | 'anyscale' | 'deepinfra' | 'alephalpha' | 'groq' | 'minimax' | 'mistral' | 'mistralai' | 'anthropic' | 'perplexityai' | 'together_ai' | 'openrouter' | 'gemini', required
      - `provider` StandardProviderSettingsDTO, required
        - `key` string, nullable
      - `models` CustomModelSettingsDTO[], nullable
        - `slug` string, required
        - `extras` object, nullable
      - `harnesses` string[], nullable
    - CustomProviderDTO
      - `kind` 'custom' | 'azure' | 'bedrock' | 'sagemaker' | 'vertex_ai' | 'openai' | 'cohere' | 'anyscale' | 'deepinfra' | 'alephalpha' | 'groq' | 'minimax' | 'mistral' | 'mistralai' | 'anthropic' | 'perplexityai' | 'together_ai' | 'openrouter' | 'gemini', required
      - `provider` CustomProviderSettingsDTO, required
        - `url` string, nullable
        - `version` string, nullable
        - `key` string, nullable
        - `extras` object, nullable
      - `models` CustomModelSettingsDTO[], required
        - `slug` string, required
        - `extras` object, nullable
      - `harnesses` string[], nullable
      - `provider_slug` string, nullable
      - `model_keys` string[], nullable
    - SSOProviderDTO
      - `provider` SSOProviderSettingsDTO, required
        - `client_id` string, required
        - `client_secret` string, nullable
        - `issuer_url` string, required
        - `scopes` string[], required
        - `extra` object
    - WebhookProviderDTO
      - `provider` WebhookProviderSettingsDTO, required
        - `key` string, nullable
    - CustomSecretDTO
      - `secret` CustomSecretSettingsDTO, required
        - `format` 'text' | 'json', required
        - `content` union
          - string
          - object
  - `header` Header, required
    - `name` string, nullable
    - `description` string, nullable
  - `lifecycle` LegacyLifecycleDTO
    - `created_at` string, nullable
    - `updated_at` string, nullable
    - `updated_by_id` string, nullable
    - `updated_by` string, nullable
  - `write_only` boolean
  - `management` PublicSecretManagementDTO
    - `policy` 'manager_only', required
  - `value_status` SecretValueStatus, required
    - `configured` boolean, required
    - `preview` string, nullable

## Other responses

- `422` — Validation Error

## Changes

> 359 revisions in range; 46 could not be searched.

- **2025-06-27** `e3e84db47198` — 1 breaking
  - api path removed without deprecation

[Change history](https://skmtc.dev/agenta-ai/apis/agenta-api/changes/secrets/post.md)

---

[API](https://skmtc.dev/agenta-ai/apis/agenta-api.md) · [All operations](https://skmtc.dev/agenta-ai/apis/agenta-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/agenta-ai/agenta-api/revisions/713e4f3b7519/schema)