Skip to main content

​
Overview

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

​
List Secrets

Retrieve all secrets in an organization. 
GET /organizations/{organizationId}/secrets
​
organizationId
string
required
Organization ID

​
Response

Returns all secrets accessible to the current user or service account.
​
id
string
required
Secret unique identifier
​
organizationId
string
required
Parent organization ID
​
key
string
required
Secret name/key
​
value
string
required
Secret value (encrypted)
​
note
string
Optional notes about the secret
​
creationDate
string
required
When secret was created
​
revisionDate
string
required
Last modification date
​
projects
array
Projects containing this secret
​
read
boolean
required
Whether user has read access
​
write
boolean
required
Whether user has write access

​
Get Secret

Retrieve a specific secret by ID. 
GET /secrets/{id}
​
id
string
required
Secret ID
curl -X GET "https://api.bitwarden.com/secrets/{id}" \
  -H "Authorization: Bearer {access_token}"

​
List Secrets by Project

Retrieve all secrets in a specific project. 
GET /projects/{projectId}/secrets
​
projectId
string
required
Project ID

​
Create Secret

Create a new secret. 
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"]
  }'

​
Request Body

​
key
string
required
Secret name/key (e.g., “API_KEY”, “DATABASE_PASSWORD”)
​
value
string
required
Secret value
​
note
string
Optional description or notes
​
projectIds
array
Projects to add secret to
Secret values are encrypted by the SDK/client before sending to the server.

​
Update Secret

Update an existing secret. 
PUT /secrets/{id}
​
id
string
required
Secret ID

​
Request Body

​
key
string
required
Secret name/key
​
value
string
required
New secret value
​
note
string
Notes about the secret
​
projectIds
array
Projects containing this secret
When the value changes, a new version is automatically created for audit purposes.

​
Delete Secrets

Delete one or more secrets. 
POST /secrets/delete
​
ids
array
required
Array of secret IDs to delete

​
Response

Returns results for each deletion attempt: 
{
  "data": [
    {
      "id": "secret-guid-1",
      "error": ""
    },
    {
      "id": "secret-guid-2",
      "error": "access denied"
    }
  ]
}

​
Get Secrets by IDs

Retrieve multiple secrets by their IDs. 
POST /secrets/get-by-ids
​
ids
array
required
Array of secret IDs to retrieve

​
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: 
{
  "userAccessPolicies": [
    {
      "organizationUserId": "user-guid",
      "read": true,
      "write": false
    }
  ]
}

​
Group Access

Grant groups access to secrets: 
{
  "groupAccessPolicies": [
    {
      "groupId": "group-guid",
      "read": true,
      "write": true
    }
  ]
}

​
Service Account Access

Grant service accounts access: 
{
  "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

#!/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

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

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]
    }
)

Build docs developers (and LLMs) love

Get started for freeTalk to us