# API Keys

Dragonchain secures access to all nodes through HMAC keys, which involve a shared secret key stored both on the client and server. HMAC keys are highly secure, efficient, and allow users to add or revoke access easily.

Using `dctl` or one of the Dragonchain SDKs, the HMAC authorization headers for requests are generated automatically from the Dragonchain credentials file. This file is usually located at `~/.dragonchain/credentials` _(location may vary based on operating system, and is configurable)_. `dctl` has commands for managing keys in this file.

## Key Management

When creating a new chain, a master key will be generated. As a best practice, Dragonchain strongly recommends storing a node's master key securely, on paper or a device not connected to the Internet. If a malicious actor steals a _master_ key, it cannot be revoked. Instead of using the master key to make requests, Dragonchain recommends that a user generate a new key for each trusted user or access use case and making use of the `nickname` feature to track keys with human friendly names. These keys can be revoked at any time if they become compromised.

### Creation

<!-- TODO add create commands and description for limited access key creation (R/W) -->

To create a new key for use, you can run the following command:

```sh
$ dctl creds remote add --nickname "My New Key"
{
  "status": 201,
  "response": {
    "key": "6S0c15MghGrpMwzz9EK2j3huQTFwH1EULdmofGXPDuj",
    "id": "EAYRMSXDOSWY",
    "registration_time": 1573691665,
    "nickname": "My New Key"
  },
  "ok": true
}
```

After creation, verify that the key is available for use:

```sh
$ dctl creds remote get "EAYRMSXDOSWY"
{
  "status": 200,
  "response": {
    "id": "EAYRMSXDOSWY",
    "registration_time": 1573691665,
    "nickname": "My New Key"
  },
  "ok": true
}
```

To add this key to your local credentials file, simply run the `dctl creds local add` command with your chain's public ID and follow the prompt:

```sh
$ dctl creds local add "dLP759g8FC3iHaxE7PhvycuWxvjTTuWgBiH9ud4adRHr"
ENDPOINT: <Internal ID>.api.dragonchain.com
HMAC KEY ID: EAYRMSXDOSWY
HMAC KEY: *******************************************
Default Dragonchain set to dLP759g8FC3iHaxE7PhvycuWxvjTTuWgBiH9ud4adRHr.
Success. New Credentials written to ~/.dragonchain/credentials
```

### Default Key

The credentials file for your HMAC keys holds a default chain ID to use. If you want to view or change the default chain, you can use the following commands:

```sh
$ dctl creds local default get
dLP759g8FC3iHaxE7PhvycuWxvjTTuWgBiH9ud4adRHr
```

```sh
$ dctl creds local default set "sj8mz8RvbJMpXiYd7BACvqMfTExtfhT5zqeCj61ww9q4"
Success. Default has been set to "sj8mz8RvbJMpXiYd7BACvqMfTExtfhT5zqeCj61ww9q4".
```

### Modification

You can update the nickname of your HMAC key on the server side by using the `dctl creds remote update` command:

```sh
$ dctl creds remote update "TZRBPXYRCGSM" -n 'Root Key'
{
  "status": 200,
  "response": {
    "success": true
  },
  "ok": true
}
```

### Deletion

To delete a key that is stored on the server side, run `dctl creds remote rm`

```sh
$ dctl creds remote rm "EAYRMSXDOSWY"
{
  "status": 200,
  "response": {
    "success": true
  },
  "ok": true
}
```

To delete a key that is stored locally, run `dctl creds local rm`

```sh
$ dctl creds local rm "dLP759g8FC3iHaxE7PhvycuWxvjTTuWgBiH9ud4adRHr"
dLP759g8FC3iHaxE7PhvycuWxvjTTuWgBiH9ud4adRHr credentials have been deleted on this machine.
```

### Listing

To view a list of all server side stored HMAC keys, run `dctl creds remote ls`

```sh
$ dctl creds remote ls
{
  "status": 200,
  "response": {
    "keys": [
      {
        "id": "EAYRMSXDOSWY",
        "registration_time": 1573691665,
        "nickname": "My New Key"
      },
      {
        "id": "TZRBPXYRCGSM",
        "registration_time": 0,
        "nickname": "Root Key"
      }
    ]
  },
  "ok": true
}
```

To view a list of all locally stored HMAC keys, run `dctl creds local ls`

```sh
$ dctl creds local ls
{
  "dLP759g8FC3iHaxE7PhvycuWxvjTTuWgBiH9ud4adRHr": {
    "auth_key": "<hidden>",
    "auth_key_id": "EAYRMSXDOSWY",
    "endpoint": "undefined"
  },
  "default": {
    "dragonchain_id": "dLP759g8FC3iHaxE7PhvycuWxvjTTuWgBiH9ud4adRHr"
  }
}
```

Dragonchain suggests following all reasonable best practices for secure storage and use of API keys. If you plan to have multiple services interacting with a chain, each should use its own API key so that if the service becomes compromised its chain access can be revoked without disrupting other services. API keys that are not in use or have been compromised should be deleted as soon as possible. Even if you do not suspect that a key has been compromised, you should rotate keys periodically.

You can view Google's [best practices for using API keys can be found here](https://support.google.com/googleapi/answer/6310037?hl=en).