Skip to main content

Keystore API

Every node has a built-in keystore. Clients create users on the keystore, which act as identities to be used when interacting with blockchains. A keystore exists at the node level, so if you create a user on a node it exists only on that node. However, users may be imported and exported using this API.

You should only create a keystore user on a node that you operate, as the node operator has access to your plaintext password.

For validation and delegation on main net, you should issue transactions through the wallet. That way control keys for your funds won't be stored on the node, which significantly lowers the risk should a computer running a node be compromised.

Format​

This API uses the json 2.0 API format. For more information on making JSON RPC calls, see here.

Endpoint​

/ext/keystore

Methods​

keystore.createUser​

Create a new user with the specified username and password.

Signature​

keystore.createUser(
    {
        username:string,
        password:string
    }
) -> {success:bool}
  • username and password can be at most 1024 characters.
  • Your request will be rejected if password is too weak. password should be at least 8 characters and contain upper and lower case letters as well as numbers and symbols.

Example Call​

curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"keystore.createUser",
    "params" :{
        "username":"myUsername",
        "password":"myPassword"
    }
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/keystore

Example Response​

{
    "jsonrpc":"2.0",
    "id"     :1,
    "result" :{
        "success":true
    }
}

keystore.deleteUser​

Delete a user.

Signature​

keystore.deleteUser({username: string, password:string}) -> {success: bool}

Example Call​

curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"keystore.deleteUser",
    "params" : {
        "username":"myUsername",
        "password":"myPassword"
    }
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/keystore

Example Response​

{
    "jsonrpc":"2.0",
    "id"     :1,
    "result" :{"success" : true}
}

keystore.exportUser​

Export a user. The user can be imported to another node with keystore.importUser. The user’s password remains encrypted.

Signature​

keystore.exportUser(
    {
        username:string,
        password:string,
        encoding:string //optional
    }
) -> {
    user:string,
    encoding:string
}

encoding specifies the format of the string encoding user data. Can be either "cb58" or "hex". Defaults to "cb58".

Example Call​

curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"keystore.exportUser",
    "params" :{
        "username":"myUsername",
        "password":"myPassword"
    }
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/keystore

Example Response​

{
    "jsonrpc":"2.0",
    "id"     :1,
    "result" :{
        "user":"4CsUh5sfVwz2jNrJXBVpoPtDsb4tZksWykqmxC5CXoDEERyhoRryq62jYTETYh53y13v7NzeReisi",
        "encoding":"cb58"
    }
}

keystore.importUser​

Import a user. password must match the user’s password. username doesn’t have to match the username user had when it was exported.

Signature​

keystore.importUser(
    {
        username:string,
        password:string,
        user:string,
        encoding:string //optional
    }
) -> {success:bool}

encoding specifies the format of the string encoding user data . Can be either "cb58" or "hex". Defaults to "cb58".

Example Call​

curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"keystore.importUser",
    "params" :{
        "username":"myUsername",
        "password":"myPassword",
        "user"    :"4CsUh5sfVwz2jNrJXBVpoPtDsb4tZksWykqmxC5CXoDEERyhoRryq62jYTETYh53y13v7NzeReisi"
    }
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/keystore

Example Response​

{
    "jsonrpc":"2.0",
    "id"     :1,
    "result" :{
        "success":true
    }
}

keystore.listUsers​

List the users in this keystore.

Signature​

keystore.ListUsers() -> {users:[]string}

Example Call​

curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"keystore.listUsers"
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/keystore

Example Response​

{
    "jsonrpc":"2.0",
    "id"     :1,
    "result" :{
        "users":[
            "myUsername"
        ]
    }
}