GPG API

7 endpoints. Request and response schemas are described on the schemas page; the other tags are listed in the API index.

Endpoints

GET /api/v1/admin/gpg/keys

List GPG keys

Lists the database-managed signing keys plus the read-only entry for the key configured through gpg.keyPath / GPG_KEY_PATH (admin only). Private key material is never returned.

Responses

Status	Description	Body
200	List of GPG keys	application/json: object
403	Admin access required	-

Fields of the 200 response (application/json):

Field	Type	Required	Description
can_store_keys	boolean	no	False when OPENARTIFACT_SECRET_KEY is not set: keys cannot be imported or generated because private keys are only stored encrypted.
keys	array of GPGKey	no	-

POST /api/v1/admin/gpg/keys

Import GPG key

Imports an ASCII-armored private key (admin only). A passphrase-protected key is unlocked with passphrase and stored without it, sealed with OPENARTIFACT_SECRET_KEY. The key becomes the global active key when nothing signs globally yet, unless activate says otherwise.

Request body (required)

application/json: object

Field	Type	Required	Description
activate	boolean	no	Make it the global active key; default: only when nothing signs globally yet
name	string	no	Unique display name; defaults to key-<keyid>. Maximum length: 255.
passphrase	string	no	Passphrase of a protected key
private_key	string	yes	ASCII-armored private key

Responses

Status	Description	Body
201	GPG key imported	application/json: GPGKey
400	Invalid, protected (code passphrase_required), revoked or expired key	-
403	Admin access required	-
409	Name or fingerprint already exists, or OPENARTIFACT_SECRET_KEY is not set (code secret_key_required)	-

POST /api/v1/admin/gpg/keys/generate

Generate GPG key

Generates a signing key pair on the server (admin only). The private key is stored sealed and never returned; export the public key with the export route.

Request body

application/json: object

Field	Type	Required	Description
activate	boolean	no	Make it the global active key; default: only when nothing signs globally yet
algorithm	string	no	One of: ed25519, rsa4096. Default: ed25519.
comment	string	no	-
email	string	no	-
name	string	no	Maximum length: 255.
user_name	string	no	User id name; default OpenArtifact repository signing key

Responses

Status	Description	Body
201	GPG key generated	application/json: GPGKey
400	Invalid input	-
403	Admin access required	-
409	Name already exists, or OPENARTIFACT_SECRET_KEY is not set (code secret_key_required)	-

DELETE /api/v1/admin/gpg/keys/{id}

Delete GPG key

Deletes a database-managed key (admin only). An active key (global or assigned to a repository) is refused with 409 key_in_use unless force=true; the repositories it signed are then re-signed by the next applicable key or become unsigned. The config key cannot be deleted.

Parameters

Name	In	Type	Required	Description
id	path	string	yes	Key id (UUID) or config for the read-only file/env key
force	query	boolean	no	-

Responses

Status	Description	Body
204	GPG key deleted	-
400	Invalid request	application/json: Error
403	Admin access required	-
404	GPG key not found	-
409	Key is active (key_in_use) or read-only	-

PUT /api/v1/admin/gpg/keys/{id}/activate

Activate GPG key

Makes the key sign every deb, rpm and pacman repository without a key of its own (global scope), or only the named hosted deb, rpm or pacman repository when repository is given. Affected repositories are re-signed (admin only).

Parameters

Name	In	Type	Required	Description
id	path	string	yes	Key id (UUID) or config for the read-only file/env key

Request body

application/json: object

Field	Type	Required	Description
repository	string	no	Repository name; omit for the global scope

Responses

Status	Description	Body
200	The key	application/json: GPGKey
400	Repository is not a hosted deb, rpm or pacman repository	-
403	Admin access required	-
404	Key or repository not found	-
409	Read-only config key	-

DELETE /api/v1/admin/gpg/keys/{id}/activate

Deactivate GPG key

Stops the key signing globally, or for the repository named in the repository query parameter (admin only).

Parameters

Name	In	Type	Required	Description
id	path	string	yes	Key id (UUID) or config for the read-only file/env key
repository	query	string	no	-

Responses

Status	Description	Body
204	Deactivated	-
400	Invalid request	application/json: Error
403	Admin access required	-
404	Key or repository not found	-
409	The key was not active there, or it is the read-only config key	-

GET /api/v1/admin/gpg/keys/{id}/export

Export public key

Downloads the ASCII-armored public key (admin only).

Parameters

Name	In	Type	Required	Description
id	path	string	yes	Key id (UUID) or config for the read-only file/env key

Responses

Status	Description	Body
200	Armored public key	application/pgp-keys: string
400	Invalid request, including a NUL byte in the URL or the body	application/json: Error
403	Admin access required	-
404	GPG key not found	-