Openbare API van Bitwarden

De Bitwarden Public API biedt organisaties een reeks tools voor het beheren van leden, collecties, groepen, gebeurtenislogboeken en beleidsregels.

De Public API is een RESTful API met voorspelbare resource-georiënteerde URL's, accepteert JSON-gecodeerde request bodies, retourneert JSON-gecodeerde responses en gebruikt standaard HTTP response codes, authenticatie en verbs.

De openbare API is compatibel met de OpenAPI Specification (OAS3) en publiceert een compatibele swagger.json definitiebestand. Verken de OpenAPI-specificatie met de Swagger UI:

• Voor publieke cloud-gehoste instanties: https://bitwarden.com/help/api/

• Voor zelf gehoste instanties: https://your.domain.com/api/docs/

Voor cloud-hosted, https://api.bitwarden.com of https://api.bitwarden.eu.

Voor zelf gehost, https://your.domain.com/api.

Voor cloud-hosted, https://identity.bitwarden.com/connect/token of https://identity.bitwarden.eu/connect/token.

Voor zelf gehost, https://your.domain.com/identity/connect/token.

De API maakt gebruik van tokens om zich te authenticeren bij beschermde API-eindpunten. Bitwarden gebruikt een OAuth2 Client Credentials aanvraagstroom om tokens toe te kennen vanaf het eindpunt. Authenticatieverzoeken hebben client_id en client_secret als vereiste parameters.

De API Key client_id en client_secret kunnen door een eigenaar worden verkregen via de Admin Console vault door te navigeren naar Instellingen → Organisatie info scherm en naar beneden te scrollen naar de API key sectie:

Als u als eigenaar de API-sleutel wilt delen met een beheerder of andere gebruiker, gebruik dan een veilige communicatiemethode zoals Bitwarden Send.

Om een token voor toegang tot de drager te verkrijgen, doe je een POST-verzoek met Content-Type: application/x-www-form-urlencoded met je client_id en client_secret naar het authenticatie-eindpunt. Als je de API gebruikt voor organisatiebeheer, gebruik je altijd grant_type=client_credentials en scope=api.organization. Bijvoorbeeld:

Bash
curl -X POST \
  https://identity.bitwarden.com/connect/token \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=client_credentials&scope=api.organization&client_id=<ID>&client_secret=<SECRET>'

Dit verzoek resulteert in het volgende antwoord:

Bash
{
  "access_token": "<TOKEN>",
  "expires_in": 3600,
  "token_type": "Bearer"
}

In dit antwoord vertegenwoordigt 3600 de vervalwaarde (in seconden), wat betekent dat dit token 60 minuten geldig is nadat het is uitgegeven. Als u een API-aanroep doet met een verlopen token, krijgt u een 401 onbevoegd responscode.

De Bitwarden Public API communiceert met application/json requests en responses, met één uitzondering:

Het authenticatie-eindpunt verwacht een application/x-www-form-urlencoded verzoek, maar zal antwoorden met application/json.

Bash
curl -X GET \
  https://api.bitwarden.com/public/collections \
  -H 'Authorization: Bearer <TOKEN>'

Waarbij is de waarde voor de access_token: sleutel in het verkregen toegangsbewijs voor de drager.

Dit verzoek zal resulteren in een antwoord:

Bash
{
  "object": "list",
  "data": [
    {
      "object": "event",
      "type": 1000,
      "itemId": "string",
      "collectionId": "string",
      "groupId": "string",
      "policyId": "string",
      "memberId": "string",
      "actingUserId": "string",
      "date": "2020-11-04T15:01:21.698Z",
      "device": 0,
      "ipAddress": "xxx.xx.xxx.x"
    }
  ],
  "continuationToken": "string"
}

Bitwarden heeft een openbare statuspagina, waar je informatie kunt vinden over de gezondheid van diensten en incidenten voor alle diensten, inclusief de Openbare API.

De Bitwarden Public API gebruikt conventionele HTTP responscodes om het succes of falen van een API verzoek aan te geven:

Voor meer informatie over het gebruik van de Bitwarden Public API, zie de volgende artikelen:

• Bitwarden Openbare API OAS Specificatie

• Gebeurtenislogboeken