Skip to main content

API Keys

Each API key corresponds to a specific role, determining the set of permissions and access rights associated with that key. To authenticate, the API key is sent as part of the HTTP header using the X-API-KEY field. You can configure API-Keys in the appliation-local.yml or contact Securosys Support if you want to use API-Keys in combination to the JWT-Token.

# HTTP HEADER-AUTHENTICATION
# header-authentication is an HTTP-authentication header consisting of a header name: `X-API-KEY` and value, individually set by the parameters below.
apiAuthentication:
  enabled: true # http-header authentication disabled by default
  keyManagementToken: '' # Granting access to Key Generation, deletion - Endpoints: /v1/key/**
  keyOperationToken: '' # Granting access to Cryptographic Operations like: Signing, Encrypting, Wrapping, fileEncryption, Keyblocking, KeyModification (Synchronous & Asynchronous Requests)
  approverToken: '' # Granting access to Approval Tasks Endpoints: /v1/filtered**ApprovalTask, /v1/approval, /v1/task
  serviceToken: '' # Granting access to Service Endpoints: /v1/versionInfo, /v1/licenseInfo, /v1/keystore/statistics, /v1/hsm/log
  approverKeyManagementToken: '' # Granting access to Approval Management Endpoints:
API-Keys

API keys can be used alongside other authentication methods, such as mutual TLS (mTLS) and JWT Authentication, offering flexibility in securing your API interactions.

API Key Roles 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 Token (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/dataObject
  • /v1/dataObject/**
  • /v1/attestation/**
  • /v1/modify
  • /v1/synchronousModify

Key Operation Token (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/certificate/**
  • /v1/synchronousUnwrap
  • /v1/synchronousUnblock
  • /v1/synchronousSign
  • /v1/synchronousFileDecrypt
  • /v1/synchronousDecrypt
  • /v1/synchronousBlock
  • /v1/synchronousHmac
  • /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

Approver Token (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 Token (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/licenseInfo
  • /v1/keystore/statistics
  • /v1/hsm/log
  • /v1/hsm/log/**

Approver Key Management Token (approverKeyManagementToken)

  • Purpose: Provides access to approverManagement 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/**
Last updated on