Registry V3 Signing Keys

V3 signing key management endpoints

List signing keys

get

Lists signing keys for the current account/org/project with filtering and pagination. Results are ordered by creation time (newest first).

Query parameters

account_identifierstringRequired

Unique identifier for the Harness account.

org_identifierstringOptional

Unique identifier for the organization within the account.

Example: default or engineering_org

project_identifierstringOptional

Unique identifier for the project within the organization.

Example: my_project or frontend_services

pageinteger · int64Optional

The page number for pagination (0-indexed).

Used to navigate through large result sets. Combined with size parameter to control which subset of results to return.

Example: page=0 returns the first page, page=1 returns the second page

Default: 0

sizeinteger · int64 · min: 1 · max: 100Optional

The number of items to return per page.

Controls the page size for paginated results.

Example: size=50 returns up to 50 items per page

Default: 20

search_termstringOptional

Search term for filtering results.

Example: search_term=prod might match keys like "production", "prod-env", etc.

typesstring[]Optional

Filter signing keys by cryptographic system. Values match SigningKeyTypeV3, which is extensible. Example: types=GPG

Example: GPG

statusesstring[]Optional

Filter signing keys by lifecycle state. Values match SigningKeyStatusV3, which is extensible. Example: statuses=ACTIVE

Example: ACTIVE

scopestringOptional

Scope of signing keys to list

none – current space only (default)
ancestors – current space plus all parent spaces

If omitted, none is assumed. This field is extensible; clients must handle unknown values.

Responses

200

response for list signing keys

application/json

Pagination metadata.

page selects which page of results to return (0 = first page).
size controls how many items are returned per page.
hasMore is true if more results exist after this page.

hasMorebooleanRequired

True if more results exist after this page.

Example: true

pageinteger · int64Required

The current page (0-indexed)

Example: 0

sizeinteger · int64Required

Number of items per page

Example: 20

default

Error response.

application/json

get/v3/signing-keys

GET /api/v3/signing-keys?account_identifier=text HTTP/1.1
Accept: */*

{
  "hasMore": true,
  "page": 0,
  "size": 20,
  "items": [
    {
      "algorithm": "RSA",
      "createdAt": 1736360000123,
      "createdBy": {
        "display_name": "text",
        "email": "text",
        "type": "text",
        "uid": "text"
      },
      "expirationAt": 1,
      "fingerprint": "text",
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "longKeyId": "text",
      "modifiedAt": 1736360000123,
      "name": "text",
      "shortKeyId": "text",
      "size": 1,
      "source": "GENERATED",
      "status": "ACTIVE",
      "type": "GPG",
      "updatedBy": {
        "display_name": "text",
        "email": "text",
        "type": "text",
        "uid": "text"
      }
    }
  ]
}

Get signing key details

get

Retrieves detailed information about a specific signing key by ID.

Path parameters

idstringRequired

Query parameters

account_identifierstringRequired

Unique identifier for the Harness account.

Responses

200

Signing key details

application/json

default

Error response.

application/json

get/v3/signing-keys/{id}

GET /api/v3/signing-keys/{id}?account_identifier=text HTTP/1.1
Accept: */*

{
  "data": {
    "algorithm": "RSA",
    "createdAt": 1736360000123,
    "createdBy": {
      "display_name": "text",
      "email": "text",
      "type": "text",
      "uid": "text"
    },
    "expirationAt": 1,
    "fingerprint": "text",
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "longKeyId": "text",
    "modifiedAt": 1736360000123,
    "name": "text",
    "shortKeyId": "text",
    "size": 1,
    "source": "GENERATED",
    "status": "ACTIVE",
    "type": "GPG",
    "updatedBy": {
      "display_name": "text",
      "email": "text",
      "type": "text",
      "uid": "text"
    }
  }
}

Delete signing key (soft delete)

delete

Soft-deletes a signing key by marking it as DELETED. The key metadata is retained for audit purposes. The key must not be attached to any registry: if it is, the request fails with 409 and the error message lists every registry to detach first.

Path parameters

idstringRequired

Query parameters

account_identifierstringRequired

Unique identifier for the Harness account.

Responses

204

Signing key deleted successfully

No content

default

Error response.

application/json

delete/v3/signing-keys/{id}

DELETE /api/v3/signing-keys/{id}?account_identifier=text HTTP/1.1
Accept: */*

No content

Update signing key

patch

Updates a signing key's status.

Path parameters

idstringRequired

Query parameters

account_identifierstringRequired

Unique identifier for the Harness account.

Body

Request to update a signing key status

statusstring · enumRequired

New status for the key (cannot transition from REVOKED or DELETED). Intentionally a closed subset of SigningKeyStatusV3 rather than an extensible enum: DELETED is reachable only via DELETE /signing-keys/{id}, which emits a distinct audit event.

Possible values:

Responses

200

Signing key details

application/json

default

Error response.

application/json

patch/v3/signing-keys/{id}

PATCH /api/v3/signing-keys/{id}?account_identifier=text HTTP/1.1
Content-Type: application/json
Accept: */*
Content-Length: 19

{
  "status": "ACTIVE"
}

{
  "data": {
    "algorithm": "RSA",
    "createdAt": 1736360000123,
    "createdBy": {
      "display_name": "text",
      "email": "text",
      "type": "text",
      "uid": "text"
    },
    "expirationAt": 1,
    "fingerprint": "text",
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "longKeyId": "text",
    "modifiedAt": 1736360000123,
    "name": "text",
    "shortKeyId": "text",
    "size": 1,
    "source": "GENERATED",
    "status": "ACTIVE",
    "type": "GPG",
    "updatedBy": {
      "display_name": "text",
      "email": "text",
      "type": "text",
      "uid": "text"
    }
  }
}

Get public key

get

Returns the public key for a signing key in ASCII-armored format (PGP for GPG keys, PEM for RSA keys). Used by clients to verify signatures.

By default the key is returned inline as text/plain. Pass download=true to receive it as a file attachment instead, with a Content-Disposition header and a key-type-specific content type (application/pgp-keys with a .asc filename for GPG keys, application/x-pem-file with a .rsa.pub filename for RSA keys).

Path parameters

idstringRequired

Query parameters

account_identifierstringRequired

Unique identifier for the Harness account.

downloadbooleanOptional

When true, the public key is returned as a file attachment with a Content-Disposition header and a key-type-specific content type (application/pgp-keys with a .asc filename for GPG keys, application/x-pem-file with a .rsa.pub filename for RSA keys). Defaults to false, which returns the ASCII-armored key inline as text/plain.

Default: false

Responses

200

Public key content. Returned inline as text/plain by default, or as a file attachment when download=true.

Responsestring · binary

default

Error response.

application/json

get/v3/signing-keys/{id}/public-key

GET /api/v3/signing-keys/{id}/public-key?account_identifier=text HTTP/1.1
Accept: */*

binary

Generate a new signing key

post

Generates a new signing key (GPG or RSA), stores it in Harness Secret Manager, and persists metadata to the database. The private key is never stored in the database.

Query parameters

account_identifierstringRequired

Unique identifier for the Harness account.

org_identifierstringOptional

Unique identifier for the organization within the account.

Example: default or engineering_org

project_identifierstringOptional

Unique identifier for the project within the organization.

Example: my_project or frontend_services

Body

Request to generate a new signing key.

type selects the cryptographic system to generate:

GPG: OpenPGP key for package signing (Debian, RPM, Alpine)
RSA: Raw RSA key for direct signing operations

algorithm selects the underlying algorithm. Only RSA and ED25519 can be generated; other SigningKeyAlgorithmV3 values (e.g. ECDSA) are rejected with 400 here but may appear on imported keys.

Key size is not a request parameter. It is fixed per algorithm so that every generated key is one package clients are known to accept:

GPG + ED25519: 256 bits (fixed by the curve)
GPG + RSA: 4096 bits
RSA + RSA: 4096 bits

The resulting size is reported as size on the created key.

Supported combinations: GPG + ED25519, GPG + RSA, RSA + RSA. Pairing type: RSA with algorithm: ED25519 is rejected with 400.

algorithmstringRequired

Underlying cryptographic algorithm of a signing key. Known values include: RSA, ED25519, ECDSA. This field is extensible; clients must handle unknown values. Note that only RSA and ED25519 can be generated; ECDSA is only observed on imported keys.

Example: RSA

expirationAtinteger · int64 · nullableOptional

Optional expiration timestamp in Unix milliseconds

namestringRequired

Human-readable name for the key

typestringRequired

Cryptographic system of a signing key. Known values include: GPG (for Debian, RPM, Alpine), RSA (for direct signing operations). This field is extensible; clients must handle unknown values.

Example: GPG

Responses

201

Signing key details

application/json

default

Error response.

application/json

post/v3/signing-keys/generate

POST /api/v3/signing-keys/generate?account_identifier=text HTTP/1.1
Content-Type: application/json
Accept: */*
Content-Length: 63

{
  "algorithm": "RSA",
  "expirationAt": 1,
  "name": "text",
  "type": "GPG"
}

{
  "data": {
    "algorithm": "RSA",
    "createdAt": 1736360000123,
    "createdBy": {
      "display_name": "text",
      "email": "text",
      "type": "text",
      "uid": "text"
    },
    "expirationAt": 1,
    "fingerprint": "text",
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "longKeyId": "text",
    "modifiedAt": 1736360000123,
    "name": "text",
    "shortKeyId": "text",
    "size": 1,
    "source": "GENERATED",
    "status": "ACTIVE",
    "type": "GPG",
    "updatedBy": {
      "display_name": "text",
      "email": "text",
      "type": "text",
      "uid": "text"
    }
  }
}

Import an existing signing key

post

Imports an existing signing key from Harness Secret Manager by validating it and storing metadata in the database. The private key remains in the user-provided secret reference (not copied).

Query parameters

account_identifierstringRequired

Unique identifier for the Harness account.

org_identifierstringOptional

Unique identifier for the organization within the account.

Example: default or engineering_org

project_identifierstringOptional

Unique identifier for the project within the organization.

Example: my_project or frontend_services

Body

Request to import an existing signing key from secret manager. type is the cryptographic system of the key being imported.

Passphrase-protected keys are supported for both GPG and RSA. Supply passphraseSecretIdentifier and passphraseSecretSpacePath together; providing only one is rejected with 400. The passphrase is stored as a secret reference and re-read on every signing operation, so it must remain readable for the lifetime of the key.

Accepted RSA private key encodings:

PKCS#1 (RSA PRIVATE KEY), encrypted or not
PKCS#8 (PRIVATE KEY / ENCRYPTED PRIVATE KEY)
OpenSSH (OPENSSH PRIVATE KEY), encrypted or not

expirationAtinteger · int64 · nullableOptional

Optional expiration timestamp in Unix milliseconds. Priority: provided value > key's embedded expiration > no expiration. Note: RSA keys don't have embedded expiration, so this is the only way to set expiration for RSA keys.

namestringRequired

Human-readable name for the key

passphraseSecretIdentifierstring · nullableOptional

Reference to the passphrase secret. Required when the private key is encrypted, for both GPG and RSA keys, and must be provided together with passphraseSecretSpacePath.

passphraseSecretSpacePathstring · nullableOptional

Space path for the passphrase secret (e.g., "accountId/orgId/projectId"). Must be provided together with passphraseSecretIdentifier; defaults to the private key's space when omitted.

privateKeySecretIdentifierstringRequired

Reference to private key secret in Harness Secret Manager

privateKeySecretSpacePathstringRequired

Space path for the private key secret (e.g., "accountId/orgId/projectId")

typestringRequired

Cryptographic system of a signing key. Known values include: GPG (for Debian, RPM, Alpine), RSA (for direct signing operations). This field is extensible; clients must handle unknown values.

Example: GPG

Responses

201

Signing key details

application/json

default

Error response.

application/json

post/v3/signing-keys/import

POST /api/v3/signing-keys/import?account_identifier=text HTTP/1.1
Content-Type: application/json
Accept: */*
Content-Length: 187

{
  "expirationAt": 1,
  "name": "text",
  "passphraseSecretIdentifier": "text",
  "passphraseSecretSpacePath": "text",
  "privateKeySecretIdentifier": "text",
  "privateKeySecretSpacePath": "text",
  "type": "GPG"
}

{
  "data": {
    "algorithm": "RSA",
    "createdAt": 1736360000123,
    "createdBy": {
      "display_name": "text",
      "email": "text",
      "type": "text",
      "uid": "text"
    },
    "expirationAt": 1,
    "fingerprint": "text",
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "longKeyId": "text",
    "modifiedAt": 1736360000123,
    "name": "text",
    "shortKeyId": "text",
    "size": 1,
    "source": "GENERATED",
    "status": "ACTIVE",
    "type": "GPG",
    "updatedBy": {
      "display_name": "text",
      "email": "text",
      "type": "text",
      "uid": "text"
    }
  }
}

Get signing key summary

get

Returns aggregate signing key counts for the requested scope: the total number of keys, the number of registries referencing a key in that scope, and the number of ACTIVE keys expiring within the next 30 days.

Counts apply to the requested scope only — they are not rolled up from parent or child scopes.

Query parameters

account_identifierstringRequired

Unique identifier for the Harness account.

org_identifierstringOptional

Unique identifier for the organization within the account.

Example: default or engineering_org

project_identifierstringOptional

Unique identifier for the project within the organization.

Example: my_project or frontend_services

Responses

200

Aggregate signing key counts for the requested scope

application/json

default

Error response.

application/json

get/v3/signing-keys/summary

GET /api/v3/signing-keys/summary?account_identifier=text HTTP/1.1
Accept: */*

{
  "data": {
    "expiringSoon": 2,
    "referencedRegistries": 4,
    "totalKeys": 16
  }
}

PreviousRegistry V3 Tree View

NextAnomalies Ignorelist Rule

Last updated 19 hours ago

Was this helpful?