Ana içeriğe geç

Import Key File

Endpoint​

POST /apiops/projects/{projectName}/keys/import-file/
bilgi

This uploads the raw material. To restore a key from an Apinizer package produced by Export Key, use Import Key instead.

Authentication​

Requires a Personal API Access Token.

Authorization: Bearer YOUR_TOKEN

Request​

Headers​

HeaderValueRequired
AuthorizationBearer {token}Yes
Content-Typemultipart/form-dataYes

Path Parameters​

ParameterTypeRequiredDescription
projectNamestringYesProject name

Form Fields​

FieldTypeRequiredDefaultDescription
keyFilefileYes—The key file (PEM, or Base64 that decodes to PEM), or the ZIP produced by Export Key File
keyNamestringYes—Name of the key to create or update
keyTypestringYes—SECRET_KEY, PRIVATE_KEY or PUBLIC_KEY
algorithmstringConditional—Symmetric key algorithm: AES, DES, DESede, or RSA. Required when creating a new SECRET_KEY (no existing key of that name). With override=true, it's optional — omit it to keep the existing key's algorithm. Unlike the JSON createKey/updateKey body, this form field is case-insensitive (aes, AES, desede are all accepted).
environmentListstringConditional—Comma-separated environment names. Required for a single file; ignored for a ZIP, whose environments come from its entries
environmentMappingstring (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
keyDescriptionstringNo—Description
aliasstringNo—Alias stored with the material
overridebooleanNofalseWhen true, updates an existing key of that name; otherwise a new key is created

Response​

Success Response (200 OK)​

{
  "status": "SUCCESS"
}

When the key was stored but could not be deployed to its environments, the response says so:

{
  "status": "SUCCESS",
  "resultMessage": "Key was saved successfully but deployment to environments failed. Details: ...",
  "deploymentResult": {
    "success": false,
    "detailList": []
  }
}

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 key (my-key) and was not imported."
  ]
}

Error Response (400 Bad Request)​

{
  "status": "FAILURE",
  "resultMessage": "Key (name: signing-key) is already exist! Send override=true to update it."
}

or

{
  "status": "FAILURE",
  "resultMessage": "Unknown keyType (RSA)! Supported values: SECRET_KEY, PRIVATE_KEY, PUBLIC_KEY"
}

or

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

or

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

or

{
  "status": "FAILURE",
  "resultMessage": "Key content is neither PEM nor valid Base64 for key type PRIVATE_KEY! Send the PEM content Base64-encoded."
}

or, creating a new SECRET_KEY without algorithm:

{
  "status": "FAILURE",
  "resultMessage": "algorithm is required for SECRET_KEY! Supported values: AES, DES, DESede, RSA"
}

or, an unrecognized algorithm value:

{
  "status": "FAILURE",
  "resultMessage": "Unknown algorithm (foo)! Supported values: AES, DES, DESede, RSA"
}

Common Causes​

  • A key of that name already exists and override was not set
  • override=true was sent but no key of that name exists
  • keyType is not one of the three supported values
  • algorithm is missing while creating a new SECRET_KEY, or is not one of the four supported values
  • environmentList is empty, or names an environment the user cannot reach
  • The uploaded file is neither PEM nor Base64 that decodes to PEM

Error Response (401 Unauthorized)​

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

cURL Example​

Example 1: Create a Key from a PEM File​

curl -X POST \
  "https://demo.apinizer.com/apiops/projects/MyProject/keys/import-file/" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "keyFile=@signing-key.pem" \
  -F "keyName=signing-key" \
  -F "keyType=PRIVATE_KEY" \
  -F "environmentList=Production,UAT"

Example 2: Replace an Existing Key​

curl -X POST \
  "https://demo.apinizer.com/apiops/projects/MyProject/keys/import-file/" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "keyFile=@signing-key-rotated.pem" \
  -F "keyName=signing-key" \
  -F "keyType=PRIVATE_KEY" \
  -F "environmentList=Production" \
  -F "override=true"

Example: Restore a Multi-Environment Key from its Export​

curl -X POST \
  "https://demo.apinizer.com/apiops/projects/MyProject/keys/import-file/" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "keyFile=@my-key-keys.zip" \
  -F "keyName=my-key" \
  -F "keyType=PRIVATE_KEY" \
  -F "override=true"
bilgi

keyType is always required, even with override=true and a ZIP whose per-environment material already carries the type — the field has no default and is applied unconditionally on top of the existing key. Use the algorithm form field instead if the key being restored is a SECRET_KEY.

Notes and Warnings​

  • A ZIP restores each environment from its own entry: entries are matched by the <keyName>-<environmentName>.pem 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.
  • Environments are merged, never wiped: an environment this upload does not name keeps the material it already had. Per-environment material normally differs, so an import that replaced the whole list would make a multi-environment object impossible to restore. To remove an environment deliberately, use the update endpoint with the list you want to keep.
  • One file, every named environment: the uploaded material is written to each environment in environmentList. To give environments different material, call the endpoint once per environment, or upload the export archive.
  • An empty environment list is rejected: material written to no environment reaches nothing, while the call would still read success. A ZIP upload does not need one — its entries carry the environments.
  • PEM or Base64: the same shapes Create Key accepts. Base64 content is decoded and must yield PEM.
  • Algorithm: required for a new SECRET_KEY; with override=true it's optional and, if omitted, the existing key keeps its current algorithm. Unlike the JSON body endpoints, this form field is case-insensitive.
  • The file name is remembered: its extension is reused when the key is downloaded again through Export Key File.
  • Deployment is reported, not assumed: a key that saved but failed to reach its environments returns success together with the deployment detail, rather than a bare success.

Permissions​

  • User must have SECRETS + EXPORT_IMPORT permission in the project
En son tarihinde güncellendi