Import Certificate File

Endpoint

POST /apiops/projects/{projectName}/certificates/import-file/

Why not Create / Update Certificate?

Create Certificate and Update Certificate add an environment entry unconditionally, so uploading a certificate for an environment it already covers leaves two entries for that environment. This endpoint replaces that environment's entry instead, and leaves the environments it does not name untouched — the same rule Import Key File and Import Keystore File follow.

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

Path Parameters

Parameter	Type	Required	Description
projectName	string	Yes	Project name

Form Fields

Field	Type	Required	Default	Description
certificateFile	file	Yes	—	A certificate file (PEM or DER), or the ZIP produced by Export Certificate
certificateName	string	Yes	—	Name of the certificate to create or update
alias	string	Yes	—	Alias the certificate is stored under
environmentList	string	Conditional	—	Comma-separated environment names. Required for a single file; ignored for a ZIP, whose environments come from its entries
environmentMapping	string (JSON)	No	—	Maps an environment name in the archive to one on this installation, for example {"UAT": "Production"}. An empty value marks that environment as deliberately not transferred. Only meaningful for a ZIP
certificateDescription	string	No	—	Description

Response

Success Response (200 OK)

{
  "status": "SUCCESS"
}

When part of the upload could not be carried over, the response says so:

{
  "status": "SUCCESS",
  "unresolvedReferences": [
    "Environment (Staging) was deliberately left out by the caller's mapping.",
    "Archive entry (README.txt) does not name an environment of certificate (partner-ca) and was not imported."
  ]
}

Error Response (400 Bad Request)

{
  "status": "FAILURE",
  "resultMessage": "Alias (partner-ca) is already used for another certificate, try changing this value!"
}

or

{
  "status": "FAILURE",
  "resultMessage": "Environment (Staging) is not found or user does not have privilege to access it!"
}

or

{
  "status": "FAILURE",
  "resultMessage": "This archive holds no importable material for certificate (partner-ca)! Entries must be named <certificateName>-<environmentName>.cer, as the export writes them."
}

Common Causes

• The alias is already taken by a different certificate in that environment
• An environment name cannot be reached by the user
• The archive's entries do not follow the naming the export writes, so no environment could be read from them
• environmentList is empty while a single file was uploaded

Error Response (401 Unauthorized)

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

cURL Example

Example 1: One Certificate into Two Environments

curl -X POST \
  "https://demo.apinizer.com/apiops/projects/MyProject/certificates/import-file/" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "certificateFile=@partner-ca.cer" \
  -F "certificateName=partner-ca" \
  -F "alias=partner-ca" \
  -F "environmentList=Production,UAT"

Example 2: Restore a Multi-Environment Certificate from its Export

curl -X POST \
  "https://demo.apinizer.com/apiops/projects/MyProject/certificates/import-file/" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "certificateFile=@partner-ca-certificates.zip" \
  -F "certificateName=partner-ca" \
  -F "alias=partner-ca"

Example 3: Rename Environments While Restoring

curl -X POST \
  "https://demo.apinizer.com/apiops/projects/MyProject/certificates/import-file/" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "certificateFile=@partner-ca-certificates.zip" \
  -F "certificateName=partner-ca" \
  -F "alias=partner-ca" \
  -F 'environmentMapping={"UAT":"Production","Staging":""}'

Notes and Warnings

• Environments are merged, never wiped: an environment this upload does not name keeps the certificate it already had. Certificate material usually differs per environment, so an import that replaced the whole list would make a multi-environment certificate impossible to restore.
• A ZIP restores each environment from its own entry: entries are matched by the <certificateName>-<environmentName>.cer naming the export writes. Anything else in the archive is reported in unresolvedReferences rather than guessed at — writing material into the wrong environment is silent and permanent.
• PEM or DER: both are accepted, with or without the -----BEGIN CERTIFICATE----- armour.
• Aliases are unique per environment: an alias already used by a different certificate in that environment is rejected.
• To remove an environment deliberately, use Update Certificate with the environment list you want to keep.

Permissions

• User must have SECRETS + EXPORT_IMPORT permission in the project

Related Documentation

• Export Certificate - Download the certificate material
• Import Truststore File - Push a whole bundle of CA certificates into one environment
• Create Certificate - Create a certificate the classic way