Skip to main content
The API service is the primary REST API for Bitwarden Server, handling all vault operations, account management, organization administration, and integrations with client applications.

​
Overview

The API service provides comprehensive endpoints for:
  • Vault Management: Ciphers, folders, collections, and sync operations
  • Account Operations: User registration, authentication, profile management
  • Organization Administration: Organization and user management, groups, policies
  • Secrets Manager: Service accounts, projects, and secrets
  • Billing: Subscription management, payment processing
  • Send: Secure file and text sharing
  • Public API: Organization-level API for integrations

​
Architecture

​
Configuration

​
Application Settings

The API service is configured via appsettings.json and environment variables:
appsettings.json
{
  "globalSettings": {
    "selfHosted": false,
    "siteName": "Bitwarden",
    "projectName": "Api",
    "stripe": {
      "apiKey": "SECRET"
    },
    "sqlServer": {
      "connectionString": "SECRET"
    },
    "identityServer": {
      "certificateThumbprint": "SECRET"
    },
    "storage": {
      "connectionString": "SECRET"
    },
    "serviceBus": {
      "connectionString": "SECRET",
      "applicationCacheTopicName": "SECRET"
    }
  }
}

​
Rate Limiting

Rate limiting is automatically enabled for cloud deployments and can be configured per-endpoint.
Rate Limit Configuration
{
  "IpRateLimitOptions": {
    "EnableEndpointRateLimiting": true,
    "RealIpHeader": "X-Connecting-IP",
    "HttpStatusCode": 429,
    "GeneralRules": [
      {
        "Endpoint": "post:*",
        "Period": "1m",
        "Limit": 60
      },
      {
        "Endpoint": "get:*",
        "Period": "1m",
        "Limit": 200
      }
    ]
  }
}

​
Key Endpoints

​
Vault Operations

Sync

GET /api/sync - Full vault synchronization for clients

Ciphers

/api/ciphers/* - Vault item CRUD operations

Folders

/api/folders/* - Folder management

Collections

/api/collections/* - Organization collections

​
Account Management

1

Account Registration

POST /api/accounts/register - Create new user account
2

Profile Management

GET/PUT /api/accounts/profile - User profile operations
3

Two-Factor

/api/two-factor/* - 2FA configuration and verification

​
Organization Administration

Located in /src/Api/AdminConsole/Controllers/:
Key Controllers
// Organization management
OrganizationsController.cs - Organization CRUD, upgrades, licensing
OrganizationUsersController.cs - Member invitations, role management
GroupsController.cs - Group management and permissions
PoliciesController.cs - Organization policies

// SSO and domain verification
OrganizationConnectionsController.cs - SSO connections
OrganizationDomainController.cs - Domain verification

​
Public API

The Public API provides organization-level access for integrations: 
curl -X GET "https://api.bitwarden.com/public/members" \
  -H "Authorization: Bearer {api_key}"

​
Service Configuration

​
Startup Configuration

From src/Api/Startup.cs:59:
Service Registration
public void ConfigureServices(IServiceCollection services)
{
    // Settings
    var globalSettings = services.AddGlobalSettingsServices(Configuration, Environment);
    
    // Data Protection
    services.AddCustomDataProtectionServices(Environment, globalSettings);
    
    // Stripe Billing
    StripeConfiguration.ApiKey = globalSettings.Stripe.ApiKey;
    StripeConfiguration.MaxNetworkRetries = globalSettings.Stripe.MaxNetworkRetries;
    
    // Repositories
    services.AddDatabaseRepositories(globalSettings);
    
    // Caching
    services.AddMemoryCache();
    services.AddDistributedCache(globalSettings);
    
    // Identity & Authentication
    services.AddCustomIdentityServices(globalSettings);
    services.AddIdentityAuthenticationServices(globalSettings, Environment, config =>
    {
        config.AddPolicy(Policies.Application, policy =>
        {
            policy.RequireAuthenticatedUser();
            policy.RequireClaim(JwtClaimTypes.Scope, ApiScopes.Api);
        });
    });
    
    // Business Services
    services.AddBaseServices(globalSettings);
    services.AddDefaultServices(globalSettings);
    services.AddBillingOperations();
    services.AddImportServices();
    services.AddSendServices();
}

​
Authentication Policies

The API uses multiple authorization policies:
PolicyScopePurpose
ApplicationapiStandard API access
WebapiWeb vault specific
Pushapi.pushPush notification registration
Licensingapi.licensingLicense validation
Organizationapi.organizationPublic organization API
Secretsapi or api.secretsSecrets Manager access

​
Middleware Pipeline

From src/Api/Startup.cs:234:
Request Pipeline
public void Configure(IApplicationBuilder app)
{
    // Security headers
    app.UseMiddleware<SecurityHeadersMiddleware>();
    
    // Rate limiting (cloud only)
    if (!globalSettings.SelfHosted)
    {
        app.UseMiddleware<CustomIpRateLimitMiddleware>();
    }
    
    // Localization
    app.UseCoreLocalization();
    
    // Static files
    app.UseStaticFiles();
    
    // Routing
    app.UseRouting();
    
    // CORS
    app.UseCors(policy => policy
        .SetIsOriginAllowed(o => CoreHelpers.IsCorsOriginAllowed(o, globalSettings))
        .AllowAnyMethod()
        .AllowAnyHeader()
        .AllowCredentials());
    
    // Authentication & Authorization
    app.UseAuthentication();
    app.UseAuthorization();
    
    // Current context
    app.UseMiddleware<CurrentContextMiddleware>();
    
    // Endpoints
    app.UseEndpoints(endpoints =>
    {
        endpoints.MapDefaultControllerRoute();
        endpoints.MapHealthChecks("/healthz");
    });
}

​
Secrets Manager

Secrets Manager endpoints are available in the commercial version only.
Secrets Manager provides secure storage and access control for application secrets:
  • Service Accounts: Machine identity for API access
  • Projects: Logical grouping of secrets
  • Secrets: Key-value pairs with versioning
  • Access Policies: Fine-grained permissions
Controllers located in /src/Api/SecretsManager/Controllers/: 
ServiceAccountsController.cs
ProjectsController.cs
SecretsController.cs
SecretVersionsController.cs
AccessPoliciesController.cs

​
Health Checks

Health checks are only enabled for cloud deployments by default.
The API exposes two health check endpoints:
  • /healthz - Basic health check
  • /healthz/extended - Detailed health information including database connectivity

​
Swagger Documentation

API documentation is available via Swagger UI in development and self-hosted deployments: 
URL: {api_url}/docs
Endpoint: {api_url}/specs/public/swagger.json
From src/Api/Startup.cs:294:
Swagger Configuration
if (Environment.IsDevelopment() || globalSettings.SelfHosted)
{
    app.UseSwagger(config =>
    {
        config.RouteTemplate = "specs/{documentName}/swagger.json";
    });
    
    app.UseSwaggerUI(config =>
    {
        config.DocumentTitle = "Bitwarden API Documentation";
        config.RoutePrefix = "docs";
        config.SwaggerEndpoint($"{globalSettings.BaseServiceUri.Api}/specs/public/swagger.json",
            "Bitwarden Public API");
    });
}

​
Background Jobs

The API service runs background jobs for:
  • Cache Synchronization: ServiceBus-based cache invalidation
  • Event Processing: Handling event integrations (Slack, Teams)
  • Scheduled Tasks: Cleanup and maintenance operations
From src/Api/Startup.cs:219:
Job Services
Jobs.JobsHostedService.AddJobsServices(services, globalSettings.SelfHosted);
services.AddHostedService<Jobs.JobsHostedService>();

if (CoreHelpers.SettingHasValue(globalSettings.ServiceBus.ConnectionString))
{
    services.AddHostedService<Core.HostedServices.ApplicationCacheHostedService>();
}

​
Deployment

​
Environment Variables

Key environment variables for the API service: 
GLOBALSETTINGS__SELFHOSTED=true
GLOBALSETTINGS__SQLSERVER__CONNECTIONSTRING=<connection_string>
GLOBALSETTINGS__IDENTITYSERVER__CERTIFICATETHUMBPRINT=<thumbprint>
GLOBALSETTINGS__STRIPE__APIKEY=<stripe_key>

​
Docker

docker run -d \
  --name bitwarden-api \
  -p 5000:5000 \
  -e GLOBALSETTINGS__SelfHosted=true \
  -e GLOBALSETTINGS__SqlServer__ConnectionString="<connection_string>" \
  bitwarden/api:latest

​
Performance Considerations

Distributed Cache

Uses Redis for distributed caching to improve performance across multiple instances

Rate Limiting

Endpoint-level rate limiting prevents abuse and ensures fair usage

Connection Pooling

Database connection pooling for efficient resource utilization

Async Operations

Fully async controllers and services for better throughput

Build docs developers (and LLMs) love

Get started for freeTalk to us