> ## Documentation Index
> Fetch the complete documentation index at: https://docs.allium.so/llms.txt
> Use this file to discover all available pages before exploring further.

# Create secret

> Store a secret value for your organization.

Stores a named secret for the organization that owns your API key and returns its ID. Use the ID to read, update, or delete the secret.

```bash theme={null}
curl -X POST https://api.allium.so/api/v1/secrets \
  -H "X-API-KEY: ${ALLIUM_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "webhook-signing-key",
    "value": "s3cr3t-value"
  }'
```

**Response:**

```json theme={null}
{ "id": "<secret_id>" }
```

> [!NOTE]
>
> Secret values are write-only. They are stored in Google Cloud Secret Manager, and no endpoint returns them, so keep your own copy if you need it.

Names are unique within your organization and can't be changed later. Creating a secret with a name that's already in use returns `409`. Your API key must belong to an organization, otherwise the request returns `404`.


## OpenAPI

````yaml _openapi/account-api.json POST /api/v1/secrets
openapi: 3.1.0
info:
  title: Allium Account API
  version: 0.1.0
servers:
  - url: https://api.allium.so
security: []
paths:
  /api/v1/secrets:
    post:
      tags:
        - SECRETS
      summary: Create Secret
      operationId: create_org_secret_api_v1_secrets_post
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOrgSecretRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateOrgSecretResponse'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          description: A secret with this name already exists in your organization
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
      security:
        - APIKeyBearer: []
components:
  schemas:
    CreateOrgSecretRequest:
      properties:
        name:
          type: string
          minLength: 1
          title: Name
          description: >-
            Secret name. Unique within your organization and cannot be changed
            later.
        value:
          type: string
          minLength: 1
          title: Value
          description: 'Secret value. Write-only: no endpoint returns it.'
      type: object
      required:
        - name
        - value
      title: CreateOrgSecretRequest
    CreateOrgSecretResponse:
      properties:
        id:
          type: string
          title: Id
          description: ID of the new secret.
      type: object
      required:
        - id
      title: CreateOrgSecretResponse
    ErrorMessage:
      properties:
        message:
          type: string
          title: Message
      type: object
      required:
        - message
      title: ErrorMessage
  responses:
    NotFound:
      description: >-
        The secret does not exist in your organization, or the API key does not
        belong to an organization
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
  securitySchemes:
    APIKeyBearer:
      type: apiKey
      in: header
      name: X-API-KEY

````