Configure API Keys

API keys are sent in the X-API-KEY header field of a HTTP request, for example X-API-KEY: foobar.

Each API key corresponds to a specific role, determining the set of permissions and access rights associated with that key. See the role overview given below. API keys are configured for each role individually.

tip

API keys can be used alongside other authentication methods, such as mTLS and JWTs.

Configuration

For on-premise deployments, configure API keys in the config-files/application-local.yml as shown below. For CloudHSM, contact Securosys Support if you want to use API keys in addition to the JWT token.

apiAuthentication:
  enabled: true # Enable API keys. Disabled by default.

  keyManagementToken: '' # Grants access to Key & Certificate Endpoints: /v1/key/**
  keyOperationToken: '' # Grants access to Cryptographic Operations like: Signing, Encrypting, Wrapping, fileEncryption, Keyblocking, KeyModification (Synchronous & Asynchronous Requests)
  approverToken: '' # Grants access to Approval Tasks Endpoints: /v1/filtered**ApprovalTask, /v1/approval, /v1/task
  serviceToken: '' # Grants access to Service Endpoints: /v1/versionInfo, /v1/licenseInfo, /v1/keystore/statistics, /v1/hsm/log
  approverKeyManagementToken: '' # Grants access to Approval Management Endpoints:

Role Overview

The API employs different roles, each tailored to specific tasks. Below is a detailed explanation of each role and the endpoints they protect:

Key Management (keyManagementToken)

• Purpose: Provides access to create, modify, or delete HSM keys and manage their lifecycle. This token is required for all operations related to key management.
• Protected Endpoints: The following endpoints can only be accessed using the keyManagementToken:

Key Management Endpoints

• /v1/key
• /v1/key/**
• /v1/key/**/attributes
• /v1/importedKey
• /v1/derivedKey
• /v1/rotate
• /v1/dataObject
• /v1/dataObject/**
• /v1/attestation/**
• /v1/modify
• /v1/synchronousModify
• /v1/certificate/**
• /v1/xpub/**

---

Key Operation (keyOperationToken)

• Purpose: Allows execution of cryptographic functions, including encryption, decryption, signing, and certificate issuance. This token is necessary for performing key-based operations.
• Protected Endpoints: The following endpoints require a keyOperationToken for access:

Key Operation Endpoints

• /v1/synchronousUnwrap
• /v1/synchronousUnblock
• /v1/synchronousSign
• /v1/synchronousFileDecrypt
• /v1/synchronousDecrypt
• /v1/synchronousBlock
• /v1/synchronousHmac
• /v1/encapsulate
• /v1/decapsulate
• /v1/synchronousFileSignEncrypt
• /v1/synchronousFileVerifyDecrypt
• /v1/fileEncrypt
• /v1/wrap
• /v1/verify
• /v1/encrypt
• /v1/fileEncrypt
• /v1/createRfcTimestamp
• /v1/generateRandom/**
• /v1/unwrap
• /v1/unblock
• /v1/sign
• /v1/decrypt
• /v1/block
• /v1/request/**
• /v1/filteredRequests

---

Approvers (approverToken)

• Purpose: Required for actions that involve approvals for Multi Authorization. It ensures that only authorized approvers can confirm sensitive operations.
• Protected Endpoints: The following endpoints require the approverToken for access:

Approval Endpoints

• /v1/filtered**ApprovalTask
• /v1/approval
• /v1/task
• /v1/approver/onboard

---

Service Information (serviceToken)

• Purpose: Provides access to general service-level information and statistics that do not fall under key management or cryptographic operations. Can also be used as health-check endpoints.
• Protected Endpoints: The following endpoints are accessible with the serviceToken:

Service Endpoints

• /v1/versionInfo
• /v1/hsmVersionInfo
• /v1/licenseInfo
• /v1/keystore/statistics
• /v1/hsm/log
• /v1/hsm/log/**
• /v1/systemTime/**

---

Approver Key Management Token (approverKeyManagementToken)

• Purpose: Provides access to approver management endpoints to manage approver(s) in conjunction with the Securosys Authorization App
• Protected Endpoints: The following endpoints are accessible with the approverKeyManagementToken:

Approver Management Endpoints

• /v1/approverManagement/**