API keys

An API key corresponds to a static session in the BPC. Like a UserSession, this contains attributes such as assigned organizations, roles and rights. Each API key contains a defined validity period. In addition, it can be specified by whom and for whom this API key was issued.

Use of the API key

API keys are used both when calling API endpoints and when configuring deployment systems.

Calling an API endpoint

To access the BPC API, there are two options in addition to the normal user login aPI. This enables direct authentication when calling the API. Without an API key, a separate authentication call must be made before accessing an API function.

In order for the BPC to accept the API key for authentication, it must be sent in the HTTP header X-APIKey.

Example

curl --header "X-APIKey: bed3a955ce73feb7186bd3f4a689a6f46b7b6264c30d0236dde87a26fc5acdbf" 'http://localhost:8181/cxf/bpc-core/status'

Deployment system

In order for the Deployment function can be used, deployment systems must be created as Backend Connections of type deployment_system (see Backend Connections). An API key must be stored for each of these deployment systems.

Administration of API keys

API keys are administered via a system setting in which both the technical parameters and the individual access authorizations are defined. An editor is available for convenient editing.

Editor

Administration via the API Keys Editor takes place under Settings → Core Services → API Keys.

Screenshot of the API Key Editor

Setting

API keys can also be configured directly via the core setting API_Keys.

Example configuration API_Keys

[
  {
    "id": "API-5d5a67b",
    "apiKey": "bed3a955ce73feb7186bd3f4a689a6f46b7b6264c30d0236dde87a26fc5acdbf",
    "name": "Beispiel API Key",
    "issuedBy": "bpcadmin",
    "issuedFor": "",
    "issuedOn": "2025-10-17T11:08:34Z",
    "expiresOn": "2026-10-17T09:46:12Z",
    "description": "Das ist ein Beispiel-API-Key",
    "assignedOrganisations": [],
    "assignedRoles": [
      "bpcuser"
    ],
    "assignedRights": []
  }
]

Configuration parameters of an API key

The various Parameters and associated functions are described below.

Setting (Key) Type Description

Setting (Key)	Type	Description
ID (`id`)	text	The ID of the API key.
API Key (`apiKey`)	text	The API key that must be used when calling an API endpoint, for example.
Name (`name`)	text	A freely assignable name, e.g. for the intended use.
Issued by (`issuedBy`)	text	Name of the user who created the API key.
Issued for (`issuedFor`)	text	Name of the user for whom the API key was issued.
Issued on (`issuedOn`)	text	Date on which the API key was issued. Date format "yyyy-MM-dd’T’HH:mm:ssZ"
Valid until (`expiresOn`)	text	Date from which the API key becomes invalid. Date format "yyyy-MM-dd’T’HH:mm:ssZ"
Comment (`description`)	text	Additional information on the API key.
Assignments / Organizations (`assignedOrganisations`)	array	API key belongs to this organization.
Assignments / Roles (`assignedRoles`)	array	API key belongs to these roles.
Assignments / rights (`assignedRights`)	array	API key has these rights.

ID
(id)

text

The ID of the API key.

API Key
(apiKey)

text

The API key that must be used when calling an API endpoint, for example.

Name
(name)

text

A freely assignable name, e.g. for the intended use.

Issued by
(issuedBy)

text

Name of the user who created the API key.

Issued for
(issuedFor)

text

Name of the user for whom the API key was issued.

Issued on
(issuedOn)

text

Date on which the API key was issued. Date format "yyyy-MM-dd’T’HH:mm:ssZ"

Valid until
(expiresOn)

text

Date from which the API key becomes invalid. Date format "yyyy-MM-dd’T’HH:mm:ssZ"

Comment
(description)

text

Additional information on the API key.

Assignments / Organizations
(assignedOrganisations)

array

API key belongs to this organization.

Assignments / Roles
(assignedRoles)

array

API key belongs to these roles.

Assignments / rights
(assignedRights)

array

API key has these rights.

After the date specified under Gültig bis (expiresOn) has expired, the API key immediately loses its validity. This causes calls to API endpoints and deployment processes to fail until a new key is stored or the validity date is adjusted. the validity date is adjusted.

Assignments

The assignments assignedOrganisations, assignedRoles and assignedRights can be used to assign fine-grained call permissions for the API keys.

For example, the following permissions are required to call this Backup API endpoint according to the API documentation, either the role BACKUPS_ADMIN or the right BACKUPS_CREATE is required to call this backup API endpoint. If the user of the API key should only be able to call this individual API endpoint, only set the right BACKUPS_CREATE at assignedRights. If all backup endpoints should be callable instead, set the role BACKUPS_ADMIN at assignedRoles.

Keywords: