Skip to main content

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. status is active or disabled (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.
Disabling or deleting a key does not take it out of service on clusters that are already running. A cluster keeps the copy of the account’s private keys it received at start-up until it terminates. If a private key has been exposed, replace it here and with your trading partners, and treat any cluster that is still running as holding the old key until it terminates.

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.
You can also create a key without leaving the package designer. On a File Storage source or destination, open the key dropdown and choose Create a new key. If the new key can be used in that direction, it is selected on the component once it is saved.

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 (active or disabled, defaults to active)
  • private_key (armored PGP private key block)
  • passphrase (matches private_key)
  • public_key (armored PGP public key block)
Response body:
  • id, account_id, owner_id, name, description, status
  • public_key (returned in full)
  • has_private_key, has_passphrase, can_decrypt, can_encrypt
  • key_ids: comma-separated list of key IDs in the ring
  • keys: array of { key_id, fingerprint, algorithm, bits, created_at, primary } for each key in the ring
  • user_ids: user IDs embedded in the key material
  • owner: { id, name, email }
  • created_at, updated_at
private_key and passphrase are never returned.

Create example

Update example

Updates are partial. Omitting private_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.

FAQ

Q: Can I retrieve a private key after saving it? No. The private key and passphrase are write-only. To replace them, submit a new value. Q: What happens if I rotate a key while a job is running? A running cluster loads decrypt-capable keys at creation time. A key created or rotated after the cluster started is not visible to jobs on it. Run the job on a new cluster, or paste the retired key alongside the current one in the same entry so the ring covers both. Q: Do I need separate entries for each trading partner? For decryption, no. Partners encrypt to your public key, so one private-key entry can decrypt files from any partner that uses it. For encryption, yes: each partner has its own public key, so each partner needs its own entry. Q: Can I use the same entry for both encryption and decryption? Yes, if it holds both a private key and a public key. The direction is decided by the component that references it, not by the entry itself. Q: Why was my key rejected at save time? The pasted block was not a parseable OpenPGP key, was over 1 MB, or was a public block pasted into the private field. The validator does not need the passphrase, so a correct private key with a wrong or missing passphrase still saves. Q: Why does my package fail to validate after I add a PGP key? Look at the error on the file component. Common causes are a disabled key, an entry that does not have the direction the component needs (a decrypt on an entry with no private key, or an encrypt on an entry with no public key), or a path with a space, semicolon, or parenthesis in it.

ETL: File Storage Source

ETL: File Storage Destination

ETL: Global Secrets

ETL: Encrypting and Decrypting Data

Last modified on October 27, 2026