> For the complete documentation index, see [llms.txt](/llms.txt).
> A full single-fetch corpus is available at [llms-full.txt](/llms-full.txt).
---
title: "Create a secret"
description: "Create a secret. The plaintext value is encrypted at rest and never returned by any endpoint — only its masked form."
method: "POST"
endpoint: "/api/v1/secrets"
order: 2
last_verified: 2026-07-27
---

<ApiEndpoint
  method="POST"
  endpoint="/api/v1/secrets"
  description="Create a secret. The plaintext value is encrypted at rest and never returned by any endpoint — only its masked form."
>
  <section>
    ### Body parameters

    <ApiAttribute name="name" type="string" description="The secret's name, e.g. OPENAI_API_KEY." required={true} />
    <ApiAttribute name="secret" type="string" description="The plaintext value. Write-only: no response ever echoes it back." required={true} />
    <ApiAttribute name="project_id" type="string" description="The owning project's UUID." required={true} />
    <ApiAttribute name="secret_type" type="string" description="One of api_key, database_url, oauth_token, ssh_key, certificate, other." required={true} />
    <ApiAttribute name="environment_id" type="string" description="Scope the secret to a single environment. Omit to make it available in every environment." required={false} />
  </section>

  <section>
    ### Request example

    <MultiLanguageCodeBlock
      languages={["bash", "javascript"]}
      value={[
        {
          language: 'bash',
          code: `curl -X POST https://api.agnt5.com/api/v1/secrets \\
  -H "X-API-KEY: {api_key}" \\
  -H "Content-Type: application/json" \\
  -d '{
    "name": "OPENAI_API_KEY",
    "secret": "sk-...",
    "project_id": "b6f1a3e2-9c4d-4f7a-8e2b-1a2b3c4d5e6f",
    "secret_type": "api_key"
  }'`
        },
        {
          language: 'javascript',
          code: `fetch('https://api.agnt5.com/api/v1/secrets', {
  method: 'POST',
  headers: { 'X-API-KEY': apiKey, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    name: 'OPENAI_API_KEY',
    secret: 'sk-...',
    project_id: projectId,
    secret_type: 'api_key'
  })
})`
        }
      ]}
    />
  </section>
</ApiEndpoint>