Public org API

The public API is the documented, versioned org-management surface. It lives under src/Api/AdminConsole/Public/Controllers/ and is published at https://bitwarden.com/help/api/. Customers call it from CI pipelines, integrations, and Bitwarden's official Directory Connector.

Authentication

Public-API callers authenticate with org-bearer client-credentials:

1. The org admin generates an API key in the Web Vault (OrganizationApiKey).
2. The caller obtains a JWT from Identity via client_credentials with client_id="organization.<orgId>" and client_secret=<apiKey>.
3. The JWT scopes to api.organization.

The API key is rotatable; rotation invalidates the previous key.

Endpoints

Resource	Operations
Members (/public/members)	List, Get, Update, Update groups, Reinvite, Remove, Get group memberships, Patch member type.
Groups (/public/groups)	List, Get, Create, Update, Delete, Get / Update member assignments.
Collections (/public/collections)	List, Get, Update, Delete (with member/group permissions).
Policies (/public/policies/{type})	List, Get, Update.
Events (/public/events)	Query the audit log with date / event-type / actor filters.
Organization (/public/organization)	Read settings, update SCIM config, import / export.
Integrations (/public/integrations)	Manage event-integration configurations.

The exact list is generated by the Swagger pipeline; run ./dev/generate_openapi_files.ps1 for the up-to-date OpenAPI spec.

Conventions

• Resources return as { object: "<resource>", data: ... } for single items and { object: "list", data: [...], continuationToken: ... } for paged lists.
• Continuation tokens are opaque; clients must echo them back unchanged.
• Errors share the same shape as the internal API: { message, validationErrors }.

Versioning

The public API is v1. Breaking changes go through a deprecation cycle: a header Bitwarden-Migrate warns clients in advance, and the old endpoint stays alive at the previous shape until clients migrate.

Conventions enforced in code

PublicApiControllersModelConvention (src/Api/Utilities/PublicApiControllersModelConvention.cs) tags every controller in this namespace so Swagger groups them under Public. The convention also enforces the [Route("public")] prefix.

Self-host

Self-hosted instances expose the same public API on the same /public/* paths. The OrganizationApiKey is provisioned through the Admin host's standard org settings.

Entry points for modification

• New endpoint → controller in src/Api/AdminConsole/Public/Controllers/, request/response under src/Api/AdminConsole/Public/Models/. Add a Swagger description and update the OpenAPI export.
• New filter on /public/events → extend EventsController.GetMany and the underlying IEventRepository.GetManyByOrganizationActingUserAsync.
• New OrganizationConnection configuration for an integration → see systems/event-integrations.