> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/bitwarden/server/llms.txt
> Use this file to discover all available pages before exploring further.

# Secrets API

> Manage secrets in Bitwarden Secrets Manager

## Overview

Secrets store sensitive values like API keys, passwords, database credentials, and certificates.

## List Secrets

Retrieve all secrets in an organization.

```bash theme={null}
GET /organizations/{organizationId}/secrets
```

<ParamField path="organizationId" type="string" required>
  Organization ID
</ParamField>

### Response

Returns all secrets accessible to the current user or service account.

<ResponseField name="id" type="string" required>
  Secret unique identifier
</ResponseField>

<ResponseField name="organizationId" type="string" required>
  Parent organization ID
</ResponseField>

<ResponseField name="key" type="string" required>
  Secret name/key
</ResponseField>

<ResponseField name="value" type="string" required>
  Secret value (encrypted)
</ResponseField>

<ResponseField name="note" type="string">
  Optional notes about the secret
</ResponseField>

<ResponseField name="creationDate" type="string" required>
  When secret was created
</ResponseField>

<ResponseField name="revisionDate" type="string" required>
  Last modification date
</ResponseField>

<ResponseField name="projects" type="array">
  Projects containing this secret
</ResponseField>

<ResponseField name="read" type="boolean" required>
  Whether user has read access
</ResponseField>

<ResponseField name="write" type="boolean" required>
  Whether user has write access
</ResponseField>

***

## Get Secret

Retrieve a specific secret by ID.

```bash theme={null}
GET /secrets/{id}
```

<ParamField path="id" type="string" required>
  Secret ID
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.bitwarden.com/secrets/{id}" \
    -H "Authorization: Bearer {access_token}"
  ```

  ```javascript JavaScript theme={null}
  const secret = await fetch(
    `https://api.bitwarden.com/secrets/${secretId}`,
    {
      headers: {
        'Authorization': `Bearer ${accessToken}`
      }
    }
  ).then(r => r.json());

  console.log('Secret value:', secret.value);
  ```
</CodeGroup>

***

## List Secrets by Project

Retrieve all secrets in a specific project.

```bash theme={null}
GET /projects/{projectId}/secrets
```

<ParamField path="projectId" type="string" required>
  Project ID
</ParamField>

***

## Create Secret

Create a new secret.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.bitwarden.com/organizations/{organizationId}/secrets" \
    -H "Authorization: Bearer {access_token}" \
    -H "Content-Type: application/json" \
    -d '{
      "key": "API_KEY",
      "value": "sk_live_abc123...",
      "note": "Production API key for payment processing",
      "projectIds": ["project-guid"]
    }'
  ```

  ```javascript JavaScript theme={null}
  const secret = await fetch(
    `https://api.bitwarden.com/organizations/${orgId}/secrets`,
    {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${accessToken}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        key: 'DATABASE_URL',
        value: 'postgresql://user:pass@host:5432/db',
        note: 'Production database connection',
        projectIds: [projectId]
      })
    }
  );
  ```
</CodeGroup>

### Request Body

<ParamField body="key" type="string" required>
  Secret name/key (e.g., "API\_KEY", "DATABASE\_PASSWORD")
</ParamField>

<ParamField body="value" type="string" required>
  Secret value
</ParamField>

<ParamField body="note" type="string">
  Optional description or notes
</ParamField>

<ParamField body="projectIds" type="array">
  Projects to add secret to
</ParamField>

<Note>
  Secret values are encrypted by the SDK/client before sending to the server.
</Note>

***

## Update Secret

Update an existing secret.

```bash theme={null}
PUT /secrets/{id}
```

<ParamField path="id" type="string" required>
  Secret ID
</ParamField>

### Request Body

<ParamField body="key" type="string" required>
  Secret name/key
</ParamField>

<ParamField body="value" type="string" required>
  New secret value
</ParamField>

<ParamField body="note" type="string">
  Notes about the secret
</ParamField>

<ParamField body="projectIds" type="array">
  Projects containing this secret
</ParamField>

<Info>
  When the value changes, a new version is automatically created for audit purposes.
</Info>

***

## Delete Secrets

Delete one or more secrets.

```bash theme={null}
POST /secrets/delete
```

<ParamField body="ids" type="array" required>
  Array of secret IDs to delete
</ParamField>

### Response

Returns results for each deletion attempt:

```json theme={null}
{
  "data": [
    {
      "id": "secret-guid-1",
      "error": ""
    },
    {
      "id": "secret-guid-2",
      "error": "access denied"
    }
  ]
}
```

***

## Get Secrets by IDs

Retrieve multiple secrets by their IDs.

```bash theme={null}
POST /secrets/get-by-ids
```

<ParamField body="ids" type="array" required>
  Array of secret IDs to retrieve
</ParamField>

***

## Secret Versioning

Secrets Manager automatically tracks version history when secret values change.

### Version Information

Each version records:

* Secret value at that point in time
* Who made the change (user or service account)
* When the change was made

### Accessing Versions

Use the Secret Versions API to:

* List all versions of a secret
* View historical values
* Restore previous versions

***

## Access Policies

Control who can access secrets using access policies.

### User Access

Grant users direct access to secrets:

```json theme={null}
{
  "userAccessPolicies": [
    {
      "organizationUserId": "user-guid",
      "read": true,
      "write": false
    }
  ]
}
```

### Group Access

Grant groups access to secrets:

```json theme={null}
{
  "groupAccessPolicies": [
    {
      "groupId": "group-guid",
      "read": true,
      "write": true
    }
  ]
}
```

### Service Account Access

Grant service accounts access:

```json theme={null}
{
  "serviceAccountAccessPolicies": [
    {
      "serviceAccountId": "sa-guid",
      "read": true,
      "write": false
    }
  ]
}
```

***

## Best Practices

### Naming Conventions

Use clear, consistent naming:

```
ENVIRONMENT_SERVICE_PURPOSE

Examples:
PROD_STRIPE_API_KEY
STAGING_DATABASE_URL
DEV_AWS_SECRET_KEY
```

### Organization

1. **Group by Environment**: Separate prod, staging, dev
2. **Use Projects**: Group related secrets
3. **Add Notes**: Document what secrets are for
4. **Rotate Regularly**: Update secrets periodically

### Security

1. **Least Privilege**: Grant minimum required access
2. **Use Service Accounts**: For automation, not user tokens
3. **Monitor Access**: Review audit logs
4. **Rotate Keys**: Update secrets when team members leave

***

## Usage Examples

### CI/CD Pipeline

```bash theme={null}
#!/bin/bash
# Fetch secrets in deployment script

SECRETS=$(curl -s "https://api.bitwarden.com/projects/${PROJECT_ID}/secrets" \
  -H "Authorization: Bearer ${BW_SERVICE_TOKEN}")

export API_KEY=$(echo $SECRETS | jq -r '.data[] | select(.key=="API_KEY") | .value')
export DB_URL=$(echo $SECRETS | jq -r '.data[] | select(.key=="DATABASE_URL") | .value')

# Deploy application with secrets
./deploy.sh
```

### Application Startup

```javascript theme={null}
// Load secrets at application startup
const secrets = await fetch(
  `https://api.bitwarden.com/projects/${projectId}/secrets`,
  {
    headers: {
      'Authorization': `Bearer ${process.env.BW_SERVICE_TOKEN}`
    }
  }
).then(r => r.json());

// Set environment variables
secrets.data.forEach(secret => {
  process.env[secret.key] = secret.value;
});
```

### Secret Rotation

```python theme={null}
import requests
import os

# Rotate API key
new_key = generate_new_api_key()

# Update in Bitwarden
response = requests.put(
    f"https://api.bitwarden.com/secrets/{secret_id}",
    headers={"Authorization": f"Bearer {os.getenv('BW_TOKEN')}"},
    json={
        "key": "API_KEY",
        "value": new_key,
        "note": f"Rotated on {datetime.now()}",
        "projectIds": [project_id]
    }
)
```