renameKeys

The "renameKeys" action renames one or more keys in a keystore. The server looks up each key you specify. A key is case sensitive and must exactly match the key you used to store the value.

When the action cannot find a specified key or finds a key and cannot rename it, it rolls back previous changes and returns an error. It either renames all specified keys or none.

The response includes the renamed key-value pairs in the "renamedKeys" property. It includes keys it could not find in the "unmatchedKeys" property.

 

How to use "renameKeys"

Use the required "keysToRename" property to specify one or more keys you want to rename. It is an array of renamed key objects. Use the required "oldKey" and "newKey" properties to specify the existing key name and its new one.

The "oldKey" property is the original key name and the "newKey" property is the new key name.

If the old and new key names are the same, the action does nothing with that key. It is not an error.

When using the "role" keystore, you must set the "roleName" property to identify the role's keys. The action returns an error if the current session's account does not have that role. An administrator account may set and get values for any role.

When using the "user" keystore, the action uses the session's username to identify the user's keys. When an administrator account runs the action, it can optionally use the "username" property to specify the user that owns the keys. This allows an elevated account to rename keys for other accounts.

 

Request examples

Global keystore

{
  "api": "db",
  "action": "renameKeys",
  "params": {
    "keyStore": "global", 
    "renamedKeys": [ 
      {
        "oldKey": "myApp/queries/Find Errors", 
        "newKey": "myApp/queries/My Error Finder"
      }
    ]
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
 
 

Role keystore

The action uses the specified role and returns an error if the current session's account does not have that role. An administrator account may delete values for any role.

{
  "api": "db",
  "action": "renameKeys",
  "params": {
    "keyStore": "role", 
    "roleName": "operator",
    "renamedKeys": [
      { 
        "oldKey": "myKey", 
        "newKey": "myKeyRenamed"
      }
    ]
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
 
 

User keystore

The action automatically uses the session's username.

{
  "api": "db",
  "action": "renameKeys",
  "params": {
    "keyStore": "user", 
    "renamedKeys": [ 
      {
        "oldKey": "nonExistentKey", 
        "newKey": "myKeyRenamed"
      }
   ]
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
 
 

User keystore request using elevated privileges

When an administrator account runs the action, it can optionally use the "username" property to specify the account of the key-value pair. This allows an elevated account to delete key-value pairs for other accounts.

{
  "api": "db",
  "action": "renameKeys",
  "params": {
    "keyStore": "user", 
    "username": "someone_else", 
    "renamedKeys": [ 
     {
        "oldKey": "myKey", 
        "newKey": "myKeyRenamed"
      }
   ]
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
 
 

 

Response examples

Global keystore

{
  "result": {
    "keyStore": "global", 
    "renamedKeys": [
      { 
        "oldKey": "myApp/queries/Find Errors", 
        "newKey": "myApp/queries/My Error Finder"
      }
    ],
    "unmatchedKeys": []
  },
  "authToken": "replaceWithAuthTokenFromCreateSession",
  "errorCode": 0,
  "errorMessage": ""
}
 
 

Role keystore

{
  "result": {
    "keyStore": "role", 
    "roleName": "operator",
    "renamedKeys": [
      { 
        "oldKey": "myKey", 
        "newKey": "myKeyRenamed"
      }
    ],
    "unmatchedKeys": []
  },
  "authToken": "replaceWithAuthTokenFromCreateSession",
  "errorCode": 0,
  "errorMessage": ""
}
 
 

User keystore

When the requested key does not exist, "renamedKeys" is empty, but "unmatchedKeys" contains it.

{
  "result": {
    "keyStore": "user", 
    "username": "me", 
    "renamedKeys": []
    "unmatchedKeys": [
      "nonExistentKey"
    ]
  },
  "authToken": "replaceWithAuthTokenFromCreateSession",
  "errorCode": -1,
  "errorMessage": "Renamed no requested keys because one or more keys could not be found. See unmatchedKeys."
}
 
 

User keystore response using elevated privileges

{
  "result": {
    "keyStore": "user", 
    "username": "someone_else", 
    "renamedKeys": [
      { 
        "oldKey": "myKey", 
        "newKey": "myKeyRenamed"
      }
    ],
    "unmatchedKeys": []
  },
  "authToken": "replaceWithAuthTokenFromCreateSession",
  "errorCode": 0,
  "errorMessage": ""
}
 
 

 

Properties

Request properties ("params")

Property Description Default Type Limits (inclusive)

keyStore

The "keyStore" property specifies the keystore where the action stores and retrieves key-value pairs. There are three keystores: "global", "role", and "user".


The Simple Secure Key-Value API stores key-value pairs independently in each keystore; thus, the same key can exist in different keystores with different values. For example, the "settings/default/" key can exist in the global, user, and role keystores.


Within the role keystore, different roles can have the same key with different values. For example, the "operator" and "guest" roles can have their own "settings/default/" key and assign their own value to it.


Within the user keystore, different users can have the same key with different values. For example, the "db" and "sam" users can have their own "settings/default/" key and assign their own value to it.


When using the "role" keystore, you must set the "roleName" property to the name of the role that owns the key-value pair. The action returns an error when the current user does not have the specified role. An administrator account may set and get values for any role.


When using the "user" keystore, the action uses the session's username to identify the user's keys. When an administrator account runs the action, it can optionally use the "username" property to specify the user that owns the keys. This allows an elevated account to create and modify keys for other accounts.

 Required - No default value string enum

"global"

"role"

"user"

renamedKeys

The "renamedKeys" property contains an array of key-rename objects. Each key-rename object contains "oldKey" and "newKey" properties that specify the key's current and new names.
 

 { 
    "oldKey": "k1",
    "newKey": "k2"
  }
 Required - No default value array of key-rename objects 
[
  { 
    "oldKey": "k1", 
    "newKey": "k2"
  }
]

renamedKeys

.newKey

 The "newKey" property specifies the new name of a key. It is part of a key-rename object. Each key-rename object contains "oldKey" and "newKey" properties that specify the current key's name and its new name. See the "renamedKeys" property for more information. Required - No default value string 1 to 128 bytes

renamedKeys

.oldKey

 The "oldKey" property specifies the current key that will be renamed. It is part of a key-rename object. Each key-rename object contains "oldKey" and "newKey" properties that specify the current key's name and its new name. See the "renamedKeys" property for more information. Required - No default value string  1 to 128 bytes

roleName

The "roleName" property specifies the key's role, which must match an RBAC role that exists in the server. It is not used with the other keystores. 


Within the role keystore, different roles can have the same key with different values. For example, the "operator" and "guest" roles can have their own "settings/default/" key and assign their own value to it.

 Required when "keystore": "role" string 1 to 64 bytes

username

The "username" property specifies the name that uniquely identifies the account. 

 

In "alter" actions, this property specifies the account that will be altered.

 

In Key-Value actions, the "username" property is optionally used with the user keystore. It allows an administrator account or an account with the "keyValueAdmin" privilege to manage a key-value pair for another account; otherwise, the server automatically uses the session's account. This approach ensures that an ordinary account can only set and retrieve its own key-value pairs.


Within the User keystore, different users can have the same key with different values. For example, the "db" and "sam" users can have their own "settings/default/" key and assign their own value to it.
 

Required - No default value

 

Optional with default of the account name of the currently logged-in user for Key-Value actions

 

 string 1 to 64 bytes

 

Response properties ("result")

Property Description Type Limits (inclusive)

keyStore

The "keyStore" property specifies the keystore where the action stores and retrieves key-value pairs. There are three keystores: "global", "role", and "user".


The Simple Secure Key-Value API stores key-value pairs independently in each keystore; thus, the same key can exist in different keystores with different values. For example, the "settings/default/" key can exist in the global, user, and role keystores.


Within the role keystore, different roles can have the same key with different values. For example, the "operator" and "guest" roles can have their own "settings/default/" key and assign their own value to it.


Within the user keystore, different users can have the same key with different values. For example, the "db" and "sam" users can have their own "settings/default/" key and assign their own value to it.


When using the "role" keystore, you must set the "roleName" property to the name of the role that owns the key-value pair. The action returns an error when the current user does not have the specified role. An administrator account may set and get values for any role.


When using the "user" keystore, the action uses the session's username to identify the user's keys. When an administrator account runs the action, it can optionally use the "username" property to specify the user that owns the keys. This allows an elevated account to create and modify keys for other accounts.

 string enum

"global"

"role"

"user"

renamedKeys

The "renamedKeys" property contains an array of key-rename objects. Each key-rename object contains "oldKey" and "newKey" properties that specify the key's current and new names.
 

 { 
    "oldKey": "k1",
    "newKey": "k2"
  }
 array of key-rename objects 
[
  { 
    "oldKey": "k1", 
    "newKey": "k2"
  }
]

renamedKeys

.newKey

 The "newKey" property specifies the new name of a key. It is part of a key-rename object. Each key-rename object contains "oldKey" and "newKey" properties that specify the current key's name and its new name. See the "renamedKeys" property for more information. string 1 to 128 bytes

renamedKeys

.oldKey

 The "oldKey" property specifies the current key that will be renamed. It is part of a key-rename object. Each key-rename object contains "oldKey" and "newKey" properties that specify the current key's name and its new name. See the "renamedKeys" property for more information. string  1 to 128 bytes

roleName

The "roleName" property specifies the key's role, which must match an RBAC role that exists in the server. It is not used with the other keystores. 


Within the role keystore, different roles can have the same key with different values. For example, the "operator" and "guest" roles can have their own "settings/default/" key and assign their own value to it.

 string 1 to 64 bytes

unmatchedKeys

The "unmatchedKeys" property contains a list of keys that an action could not find. An application can check this property to troubleshoot issues with key names.


The following actions look up keys by exact match and return this property:

  • "getValues"
  • "describeValues"
  • "deleteValues"
  • "renameKeys"
 array of strings zero or more key strings

username

The "username" property specifies the name that uniquely identifies the account. 

 

In "alter" actions, this property specifies the account that will be altered.

 

In Key-Value actions, the "username" property is optionally used with the user keystore. It allows an administrator account or an account with the "keyValueAdmin" privilege to manage a key-value pair for another account; otherwise, the server automatically uses the session's account. This approach ensures that an ordinary account can only set and retrieve its own key-value pairs.


Within the User keystore, different users can have the same key with different values. For example, the "db" and "sam" users can have their own "settings/default/" key and assign their own value to it.
 

 string 1 to 64 bytes

Was this article helpful?

Give feedback about this article

Related Articles