Service Accounts API

Manage machine identities for automated secret access

Overview

Service accounts are machine identities designed for automated systems, CI/CD pipelines, and applications that need programmatic access to secrets.

List Service Accounts

Retrieve all service accounts in an organization.

GET /organizations/{organizationId}/service-accounts?includeAccessToSecrets={includeAccessToSecrets}

organizationId · string · required

Organization ID

includeAccessToSecrets · boolean · default: "false"

Include detailed secret access information

Response

id · string · required

Service account unique identifier

organizationId · string · required

Parent organization ID

name · string · required

Service account name

creationDate · string · required

When service account was created

revisionDate · string · required

Last modification date

accessToSecrets · number

Number of secrets this service account can access

---

Get Service Account

Retrieve a specific service account.

GET /service-accounts/{id}

id · string · required

Service account ID

---

Create Service Account

Create a new service account.

cURL

curl -X POST "https://api.bitwarden.com/organizations/{organizationId}/service-accounts" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CI/CD Pipeline"
  }'

Request Body

name · string · required

Service account name (e.g., “Production Deployment”, “Terraform”)

Creating a service account may require additional seats on your Secrets Manager subscription.

---

Update Service Account

Update a service account’s name.

PUT /service-accounts/{id}

id · string · required

Service account ID

Request Body

name · string · required

New service account name

---

Delete Service Accounts

Delete one or more service accounts.

POST /service-accounts/delete

ids · array · required

Array of service account IDs to delete

Response

Returns results for each deletion:

{
  "data": [
    {
      "id": "sa-guid-1",
      "error": ""
    },
    {
      "id": "sa-guid-2",
      "error": "access denied"
    }
  ]
}

Deleting a service account revokes all its access tokens. Active integrations will fail.

---

Access Tokens

List Access Tokens

Retrieve all access tokens for a service account.

GET /service-accounts/{id}/access-tokens

id · string · required

Service account ID

Response

id · string · required

Access token ID

name · string · required

Token name

creationDate · string · required

When token was created

expireAt · string

Token expiration date (null = no expiration)

revisionDate · string · required

Last modification date

---

Create Access Token

Generate a new access token for a service account.

POST /service-accounts/{id}/access-tokens

id · string · required

Service account ID

Request Body

name · string · required

Token name (e.g., “Production Token”, “Staging Deploy”)

encryptedPayload · string · required

Encrypted payload for the token

key · string · required

Encryption key

expireAt · string

Optional expiration date (ISO 8601 format)

Response

id · string · required

Token ID

clientSecret · string · required

The actual access token value (only returned once!)

name · string · required

Token name

creationDate · string · required

When token was created

The clientSecret is only returned when creating the token. Store it securely - you cannot retrieve it again!

---

Revoke Access Tokens

Revoke one or more access tokens.

POST /service-accounts/{id}/access-tokens/revoke

id · string · required

Service account ID

ids · array · required

Array of access token IDs to revoke

---

Access Management

Service accounts access secrets through projects. Grant access using access policies.

Grant Project Access

Allow a service account to access a project:

{
  "serviceAccountAccessPolicies": [
    {
      "serviceAccountId": "sa-guid",
      "read": true,
      "write": false
    }
  ]
}

Access Levels

• Read: Can fetch secrets
• Write: Can create/update secrets (typically not granted)

Most service accounts only need read access to fetch secrets for deployment.

---

Best Practices

Naming Conventions

Use descriptive names that indicate purpose:

[System/Tool] - [Environment]

Examples:
GitHub Actions - Production
Terraform - Staging
Kubernetes - Development
Jenkins - CI Pipeline

Security

1. Least Privilege: Only grant access to required projects
2. Rotate Tokens: Regenerate tokens periodically
3. Set Expiration: Use token expiration dates
4. Monitor Usage: Check event logs for suspicious activity
5. Revoke Unused: Delete service accounts and tokens no longer needed

Token Management

1. Name Descriptively: Indicate token purpose and location
2. Use Expiration: Set expiration dates for production tokens
3. Store Securely: Use secret management in your CI/CD system
4. One Token per System: Don’t share tokens across systems
5. Revoke Immediately: Remove compromised tokens right away

---

Usage Examples

CI/CD Integration (GitHub Actions)

name: Deploy

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v3
      
      - name: Fetch Secrets
        env:
          BW_SERVICE_TOKEN: ${{ secrets.BW_SERVICE_TOKEN }}
        run: |
          # Fetch secrets from Bitwarden
          SECRETS=$(curl -s "https://api.bitwarden.com/projects/${PROJECT_ID}/secrets" \
            -H "Authorization: Bearer ${BW_SERVICE_TOKEN}")
          
          # Export as environment variables
          echo "API_KEY=$(echo $SECRETS | jq -r '.data[] | select(.key=="API_KEY") | .value')" >> $GITHUB_ENV
      
      - name: Deploy
        run: ./deploy.sh

Terraform Provider

provider "bitwarden" {
  access_token = var.bw_service_token
}

data "bitwarden_secret" "database_url" {
  key = "DATABASE_URL"
  project_id = var.project_id
}

resource "aws_db_instance" "main" {
  # Use secret in resource
  password = data.bitwarden_secret.database_url.value
}

Docker Container

FROM node:18

WORKDIR /app

# Install Bitwarden CLI
RUN npm install -g @bitwarden/cli

# Copy startup script
COPY entrypoint.sh /
RUN chmod +x /entrypoint.sh

ENTRYPOINT ["/entrypoint.sh"]

#!/bin/bash
# entrypoint.sh

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

# Set environment variables
export DATABASE_URL=$(echo $SECRETS | jq -r '.data[] | select(.key=="DATABASE_URL") | .value')

# Start application
npm start

Kubernetes Secret Sync

import requests
import base64
from kubernetes import client, config

# Load k8s config
config.load_incluster_config()
v1 = client.CoreV1Api()

# Fetch secrets from Bitwarden
response = requests.get(
    f"https://api.bitwarden.com/projects/{project_id}/secrets",
    headers={"Authorization": f"Bearer {service_token}"}
)

secrets = response.json()['data']

# Create/update Kubernetes secret
secret_data = {}
for secret in secrets:
    secret_data[secret['key']] = base64.b64encode(
        secret['value'].encode()
    ).decode()

k8s_secret = client.V1Secret(
    metadata=client.V1ObjectMeta(name="app-secrets"),
    data=secret_data
)

v1.replace_namespaced_secret(
    name="app-secrets",
    namespace="default",
    body=k8s_secret
)

---

Service Account Limits

Service account limits vary by plan:

Plan	Service Accounts
Free (trial)	0
Teams	Starts at 20, can purchase more
Enterprise	Custom

Service accounts count toward your Secrets Manager seat limit. Contact sales to add capacity.