Import Keystore

Endpoint

POST /apiops/projects/{projectName}/keystores/import/

Authentication

Requires a Personal API Access Token.

Header

Authorization: Bearer YOUR_TOKEN

Request

Headers

Header	Value	Required
Authorization	Bearer {token}	Yes
Content-Type	multipart/form-data	Yes
X-Apinizer-Package-Passphrase	Base64 encoding of the UTF-8 passphrase	Only when the uploaded package is encrypted

Path Parameters

Parameter	Type	Required	Description
projectName	string	Yes	Project name where the keystore will be imported

Query Parameters

Parameter	Type	Required	Description
override	boolean	No	Whether to overwrite an existing keystore with the same name. Defaults to false.

Form Data

Parameter	Type	Required	Description
keystoreExportFile	file	Yes	ZIP file containing the keystore export. Must have .zip extension
environmentMapping	string (JSON)	No	Only relevant when override=false: maps an environment name in the package to an environment name on this installation, e.g. {"UAT":"Production"}. An empty value marks that environment as deliberately not transferred. Without it, same-named environments match and unmatched ones are dropped. Ignored when override=true
certEnvironmentMergeMethod	string	No	Only relevant when override=true: how the package's environment-scoped keystore data merges onto the existing keystore. MATCH_BY_NAME (default) writes only the environments named in the package, OVERWRITE_ALL writes the package's first entry onto every target environment
certEnvironmentUncoveredAction	string	No	Only relevant when override=true: what happens to a target environment the package does not cover. FILL_FROM_PACKAGE writes the package's data onto it, REMOVE_FROM_TARGET drops it from the keystore. If such an uncovered environment actually exists and this is not supplied, the import is rejected with 400 rather than silently leaving it with stale material

Notes

• File must be a valid ZIP archive
• File must end with .zip extension (case-insensitive)
• Whether the package is encrypted is detected automatically — there is no separate encrypt parameter on import
• If override=false (default) and a keystore with the same name already exists, the imported keystore's name gets an -imported suffix
• If override=true, an existing keystore with the same name is overwritten

Response

Success Response (200 OK)

{
  "status": "SUCCESS"
}

Response Fields

Field	Type	Description
status	string	Response status: SUCCESS or FAILURE

Error Response (400 Bad Request)

{
  "status": "FAILURE",
  "resultMessage": "projectName value can not be empty!"
}

or

{
  "status": "FAILURE",
  "resultMessage": "keystoreExportFile value can not be empty!"
}

or

{
  "status": "FAILURE",
  "resultMessage": "keystoreExportFile parameter must be in zip file format and must end with zip extension!"
}

or

{
  "status": "FAILURE",
  "resultMessage": "Package is encrypted; a passphrase is required."
}

or

{
  "status": "FAILURE",
  "resultMessage": "Package could not be decrypted with the given passphrase."
}

or

{
  "status": "FAILURE",
  "resultMessage": "Encrypted package could not be read."
}

or

{
  "status": "FAILURE",
  "resultMessage": "environmentMapping must be a JSON object of \"package environment name\":\"target environment name\" pairs (an empty value means \"do not transfer this environment\"). Received: {not valid json"
}

or

{
  "status": "FAILURE",
  "resultMessage": "Replace Existing of KEY_STORE 'partner-keystore' cannot proceed: the package carries no data for the target environment(s) UAT, so they would keep their old material while the rest is replaced. Send the certEnvironmentUncoveredAction parameter with either FILL_FROM_PACKAGE (write the package's data onto them) or REMOVE_FROM_TARGET (drop them from the object) and import again."
}

Common Causes

• Empty projectName
• Empty or missing file
• File is not a ZIP archive or does not have .zip extension
• Uploaded package is encrypted but the X-Apinizer-Package-Passphrase header was not provided
• Provided passphrase does not open the package
• File is not a package this version can read — corrupted or unsupported format
• environmentMapping was supplied but is not a valid JSON object of environment-name pairs
• override=true where the target keystore has an environment the package does not cover, and certEnvironmentUncoveredAction was not supplied

Error Response (401 Unauthorized)

{
  "status": "FAILURE",
  "resultMessage": "Token is not valid!"
}

cURL Example

Example 1: Import Keystore

curl -X POST \
  "https://demo.apinizer.com/apiops/projects/MyProject/keystores/import/" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "keystoreExportFile=@keystoreExportFile.zip"

Example 2: Import Keystore with Override

curl -X POST \
  "https://demo.apinizer.com/apiops/projects/MyProject/keystores/import/?override=true" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "keystoreExportFile=@keystoreExportFile.zip"

Example 3: Import an Encrypted Keystore Package

curl -X POST \
  "https://demo.apinizer.com/apiops/projects/MyProject/keystores/import/" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Apinizer-Package-Passphrase: $(printf '%s' 'MyStrongPassphrase' | base64)" \
  -F "keystoreExportFile=@keystoreExportFile.zip"

Example 4: Import as New with Environment Mapping

curl -X POST \
  "https://demo.apinizer.com/apiops/projects/MyProject/keystores/import/" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "keystoreExportFile=@keystoreExportFile.zip" \
  -F 'environmentMapping={"UAT":"Production"}'

Example 5: Replace Existing with Uncovered-Environment Handling

curl -X POST \
  "https://demo.apinizer.com/apiops/projects/MyProject/keystores/import/?override=true" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "keystoreExportFile=@keystoreExportFile.zip" \
  -F "certEnvironmentMergeMethod=MATCH_BY_NAME" \
  -F "certEnvironmentUncoveredAction=FILL_FROM_PACKAGE"

Notes and Warnings

• Override Behavior:

  • override=false (default): a suffix (-imported) is added to the name if a keystore with the same name exists
  • override=true: an existing keystore with the same name is overwritten

• Environment Mapping (override=false only):

  • environmentMapping maps an environment name in the package to an environment name on this installation, e.g. {"UAT":"Production"}
  • An empty value ({"UAT":""}) marks that environment as deliberately not transferred
  • Without it, same-named environments match and unmatched ones are dropped — today's default behavior
  • Ignored when override=true, since Replace Existing merges environments via certEnvironmentMergeMethod instead

• Certificate/Key Environment Merge (override=true only):

  • certEnvironmentMergeMethod decides how the package's environment-scoped material merges onto the existing keystore: MATCH_BY_NAME (default) only touches environments the package names, OVERWRITE_ALL writes the package's first entry onto every target environment
  • If a target environment is left uncovered by the package under MATCH_BY_NAME, the import used to silently keep that environment's old keystore material — a partial transfer with no warning. It is now blocked with a 400 unless certEnvironmentUncoveredAction says what to do with it (FILL_FROM_PACKAGE or REMOVE_FROM_TARGET)
  • Both parameters are ignored when override=false, since Import as New has no existing keystore to merge onto

• Encrypted Packages:

  • Whether the package is encrypted is detected automatically from its contents
  • X-Apinizer-Package-Passphrase is required only if the uploaded package was exported with encrypt=true
  • A wrong passphrase does not open the package; the import fails without partially applying it

• File Format:

  • File must be a valid ZIP archive
  • File must end with .zip extension (case-insensitive)

• Project Validation:

  • Project must exist
  • User must have access to the project
  • User must have SECRETS + EXPORT_IMPORT permission

Permissions

• User must have SECRETS + EXPORT_IMPORT permission in the project
• Alternatively, user can have project admin role

Related Documentation

• Export Keystore - Export a keystore to a ZIP file
• Get Keystore - Get keystore details
• List Keystores - List all keystores