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.

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

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

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