Overview
PGP keys are account-level entries that hold OpenPGP key material. A File Storage source can reference an entry to decrypt inbound files, and a File Storage destination can reference an entry to encrypt outbound files. You paste the key material once in Account Settings instead of embedding it in each component. Use a PGP key entry when:- A trading partner encrypts files to your public key and drops them in a bucket you read from.
- You send files to a trading partner and must encrypt them with the partner’s public key first.
How it works
An entry is a key ring. It holds one or both directions:
At least one of
private_key or public_key must be set. An entry with only a private key can decrypt but not encrypt. An entry with only a public key can encrypt but not decrypt. An entry with both can do either, in different components.
Integrate.io reads the private key blob as a ring and matches each file to the key it was encrypted to. You can paste current plus retired private keys into one entry and still read archived files. Use separate entries only when the passphrases differ.
What the entry stores
- Name, description, status.
statusisactiveordisabled(the Enabled checkbox in the UI). A disabled entry stays in the list but cannot be selected on a component. - Key IDs. Derived from the pasted material and shown in the UI so you can tell entries apart. A key ID is not secret. It is printed in the header of every file encrypted to that key.
- Metadata about each key in the ring. Key ID, fingerprint, algorithm, bit length, creation timestamp, and whether the key is a primary or subkey.
Write-only key material
private_key and passphrase are write-only. Once saved, the API never returns them, not even masked. The response carries has_private_key, has_passphrase, can_decrypt, and can_encrypt booleans instead.
public_key is returned in full, because it is meant to be handed to trading partners.
Rotation and clusters
The list of decrypt-capable keys is loaded onto a cluster when the cluster is created. Keys created or rotated after the cluster has started are not visible to jobs already running on it. If you rotate a key and a job cannot find it, start the job on a new cluster.Permissions
Read is granted broadly because listing keys is how a package author picks one on a file component. Write is narrower because replacing a key silently breaks every pipeline that decrypts with it.
Configuration
Adding a PGP key
1
Go to Account Settings -> PGP Keys.
2
Click New PGP key.
3
Enter a Name and optional Description.
4
Paste an armored Private key block, an armored Public key block, or both. Include the
-----BEGIN PGP ... KEY BLOCK----- and -----END PGP ... KEY BLOCK----- lines.5
If the private key is protected, enter the Passphrase.
6
Click Add PGP key. The entry is validated as a parseable OpenPGP block before it saves. A public key pasted into the private key field is rejected.
Using a PGP key on a File Storage source
Open a File Storage source and select your file storage connection. Under Advanced settings, set Decrypt file to PGP and pick a key. Only entries with a private key are offered. Integrate.io decrypts each file under the source path with a matching key from that ring before parsing it, both when a job runs and when you preview the file. Leave Decrypt file on None if the files are not encrypted. Encryption and compression can be combined in either order. Integrate.io reads the file name extensions from the right:member.csv.gz.pgp is decrypted and then decompressed, and member.csv.pgp.gz is decompressed and then decrypted.
The source path is used to scope the key to this component. Paths with a space, semicolon, or parenthesis are rejected at save time, because the runtime cannot express those in a key scope.
Using a PGP key on a File Storage destination
Open a File Storage destination and select your file storage connection. Under Advanced settings, set Encrypt output to PGP and pick a key. Only entries with a public key that can encrypt are offered. At runtime, output files are encrypted to that public key before they are written to the target path, and.pgp is appended to each output file name.
Files are compressed first and then encrypted, so the format and compression settings describe the file inside the encrypted envelope. With Gzip compression, for example, output files end in .gz.pgp.
Package validation refuses a destination that references a disabled entry, an entry that does not exist, or an entry with no public key. The alternative is a job that succeeds and ships a partner cleartext.
Deleting a PGP key
Deleting an entry removes it from the account. Any File Storage source or destination that still references it fails to run until it is pointed at another key. Deleting does not remove the key from clusters that are already running (see Rotation and clusters).API
Endpoints
Fields
Request body:name(required, up to 255 characters, unique per account, case-insensitive)description(up to 1024 characters)status(activeordisabled, defaults toactive)private_key(armored PGP private key block)passphrase(matchesprivate_key)public_key(armored PGP public key block)
id,account_id,owner_id,name,description,statuspublic_key(returned in full)has_private_key,has_passphrase,can_decrypt,can_encryptkey_ids: comma-separated list of key IDs in the ringkeys: array of{ key_id, fingerprint, algorithm, bits, created_at, primary }for each key in the ringuser_ids: user IDs embedded in the key materialowner:{ id, name, email }created_at,updated_at
private_key and passphrase are never returned.
Create example
Update example
Updates are partial. Omittingprivate_key, passphrase, or public_key leaves the stored value unchanged. Sending an explicitly empty string clears it, subject to the “at least one of private or public must be set” rule.