> ## Documentation Index
> Fetch the complete documentation index at: https://docs.basaltic.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Creating a key

> Specs, usages, and the one choice you cannot change after the key exists.

## Creating a key

<Tabs>
  <Tab title="Console">
    Go to **KMS** and choose **Create Key**. Under **Key details**
    give it a **Name** and an optional **Description**; under **Cryptography**
    pick a **Key spec** and a **Key usage**.

    The spec choices are **AES-256 symmetric (recommended)**, **RSA-2048
    asymmetric**, **RSA-4096 asymmetric** and **ECDSA P-256 asymmetric (sign
    only)**. **Key usage** is locked to whatever the chosen spec supports — an
    RSA spec is the only one that lets you choose between **Encrypt /
    Decrypt** and **Sign / Verify**.
  </Tab>

  <Tab title="API">
    ```bash theme={null}
    POST https://kms.sa-saopaulo-1.basaltic.sh/v1/keys
    {
      "name": "prod-master",
      "key_spec": "aes-256",
      "description": "Master key for the payments data store"
    }
    ```
  </Tab>

  <Tab title="CLI">
    ```bash theme={null}
    basaltic kms key create \
      --name prod-master --key-spec aes-256 \
      --description "Master key for the payments data store"
    ```
  </Tab>

  <Tab title="Go">
    ```go theme={null}
    key, err := kms.New(cfg).CreateKey(ctx, &kms.CreateKeyRequest{
        Name:        "prod-master",
        KeySpec:     "aes-256",
        Description: basaltic.String("Master key for the payments data store"),
    })
    ```

    KMS is regional; a key can only be used from the region it was created in.
  </Tab>
</Tabs>

The call is synchronous. The response carries the key already in `enabled`,
ready for crypto operations — there is nothing to poll.

`name` is unique per account and lands in the CRN, so it has to be URL-safe:
`^[a-zA-Z0-9][a-zA-Z0-9._-]{0,127}$`.

### Specs and usages

A key is pinned to one **usage** at creation: either `encrypt_decrypt` or
`sign_verify`. The **spec** decides which usages are even possible.

| `key_spec`   | Can encrypt       | Can sign      | Default usage         |
| ------------ | ----------------- | ------------- | --------------------- |
| `aes-256`    | Yes — AES-GCM     | No            | `encrypt_decrypt`     |
| `rsa-2048`   | Yes — OAEP-SHA256 | Yes           | none, you must choose |
| `rsa-4096`   | Yes — OAEP-SHA256 | Yes           | none, you must choose |
| `ecdsa-p256` | No                | Yes — SHA-256 | `sign_verify`         |

Omit `key_usage` for `aes-256` or `ecdsa-p256` and the only usage the spec
supports is applied. Omit it for an RSA spec and the request is rejected — RSA
can do both, so the service will not guess.

<Warning>
  An RSA key pinned to `encrypt_decrypt` **refuses sign and verify**, and the
  other way round, even though the algorithm could do either. The refusal is
  `400 KMS_INVALID_KEY_USAGE`. Pick the usage deliberately: neither the spec
  nor the usage can be changed later, and `PATCH /v1/keys/{key_id}` only edits
  `name`, `description` and `tags`. To change either one, create a new key.
</Warning>