Method: Create Key


This endpoint creates a new named encryption key in the specified vault.

  1. The named key is wrapped (encrypted) by the vaults key.
  2. The un-wrapped (plaintext) key material of the named key is not obtainable by any endpoints, unless:
    1. The named key is marked as exportable (allow_export) upon creation of the key.
    2. The named key is marked as backupable (allow_backup) upon creation of the key.
    3. The user calling the /export endpoint has Admin permission in the vault where the named key resides.
    4. The user calling the /backup endpoint has Admin permission in the vault where the named key resides.

The newly created named key can be used by a user with at least Read permission in the vault, to encrypt data using the /encrypt endpoint, or to decrypt data using the /decrypt endpoint without having any access, or knowledge, about the key material.

See the overview on how transparent encryption in StoredSafe can help solve key distribution problems.


Creating a key requires the Write permission in the affected vault.

URL Syntax


HTTP Method


Successful HTTP Response



Parameter name Description Parameter type Type Default Mandatory Comment
X-Http-Token StoredSafe token HTTP Header String   1) Preferred method
token StoredSafe token JSON-encoded String   1) Legacy method
vaultid Vault-ID URL-encoded String   Yes  
name Key name URL-encoded String   Yes  
type Type of key JSON-encoded String aes128-gcm96   See table below for supported types
allow_export Enables key to be exported JSON-encoded Boolean True    
allow_backup Enables key to be backed up in plaintext JSON-encoded Boolean True    
allow_delete Enable deletion of key JSON-encoded Boolean True    
info Key information JSON-encoded String      


1) One of the methods is required.

Name Description Type Signing
aes128-ofb AES-128 in OFB mode Symmetric  
aes256-ofb AES-256 in OFB mode Symmetric  
aes128-gcm96 AES-128 in GCM mode using 96 bit nonce size AEAD Symmetric  
aes256-gcm96 AES-256 in GCM mode using 96 bit nonce size AEAD Symmetric  
chacha20-poly1305 ChaCha20-Poly1305 AEAD Symmetric  
RSA-4096 RSA-4096 Asymmetric Yes
ED25519 ED25519 Asymmetric Yes

Response Attributes

Attribute Description Type
CALLINFO.errorcodes Number of errors Integer
CALLINFO.errors Number of errors Integer
CALLINFO.general Information Array
CALLINFO.handler Handler used String
CALLINFO.token Rotated StoredSafe token 1) String
CALLINFO.version Key version String
CALLINFO.objectid Object-ID String
DATA Supplied data in prior API-call String
HEADERS.(headers) HTTP Headers String
PARAMS Route parameters (empty) Array
ERRORCODES Error code and text 2) Object
ERRORS Error code and text 2) Array


1) Token to be used in subsequent calls
2) Only present if errors


Create a new named key (my-new-key) in the vault (vault-id) 179.


POST /api/1.0/transparent/179/keys/my-new-key
x-http-token: your_storedsafe_token
    "type": "aes256-gcm96",
    "info": "my new key"


HTTP/2 201
Content-type: application/json; charset=UTF-8
    "CALLINFO": {
        "errorcodes": 0,
        "errors": 0,
        "general": [],
        "handler": "EncryptionHandler",
        "status": "SUCCESS",
        "token": "rotated_storedsafe_token",
        "name": "my-new-key",
        "objectid": "8743"
    "DATA": {
        "name": "my-new-key",
        "vaultid": "179",
        "type": "aes256-gcm96",
        "info": "my new key",
        "token": "your_storedsafe_token",
    "HEADERS": {
        "Accept": "*/*",
        "Content-Length": "169",
        "Content-Type": "application/json",
        "Host": "",
        "User-Agent": "curl/7.64.1",
        "X-Http-Token": "your_storedsafe_token"
    "PARAMS": []

See the annotated example for a full example on how to use transparent encryption.