---
title: Using Bring Your Own Key with the Scaleway API and CLI
description: Learn how to use Bring Your Own Key (BYOK) with Key Manager to import your own key material and manage it with the ImportKeyMaterial and DeleteKeyMaterial endpoints.
tags: byok bring-your-own-key key-manager key-material import key-rotation
dates:
  validation: 2026-09-02
  posted: 2026-09-02
---

Bring Your Own Key (BYOK) lets you use your own encryption key material with Scaleway Key Manager. Instead of having Key Manager generate a key on your behalf, you generate the key material locally and import it into a Key Manager key. This is useful when you need to keep control over the generation of your key material, for example to meet regulatory or compliance requirements, or to maintain portability of your keys across cloud providers.

With BYOK, the responsibility for generating strong key material lies with you. Keys are not imported directly into Key Manager, as this would violate the principle that keys only exist inside Key Manager and cannot exit it. Instead, only the key material used to create a key is imported. For this reason, only AES keys can be imported, as they are derived from key material. The process of creating asymmetric keys differs, so they cannot be imported.

For more information on how imported key material is processed cryptographically, see the documentation about [customer-provided KEKs (BYOK)](/key-manager/reference-content/cryptographic-details-key-manager/#customer-provided-keks-byok).

## Requirements

To import your own key material, you need:

- A Scaleway API token. Refer to the [API documentation](https://www.scaleway.com/en/developers/api/key-manager/) for information on authentication.
- A Key Manager key created with the `external` origin and the `AES-256-GCM` symmetric encryption algorithm. This is required because only externally-originated AES keys can receive imported key material.

To create such a key, call the [CreateKey endpoint](https://www.scaleway.com/en/developers/api/key-manager/#path-keys-create-a-key) as follows:

```
    curl -X POST 'https://api.scaleway.com/key-manager/v1alpha1/regions/fr-par/keys' \
    --header 'Content-Type: application/json' \
    --header 'X-Auth-Token: <Scaleway_API_Secret_Key>' \
    --data '{
        "project_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "name": "my-byok-key",
        "usage": {
            "symmetric_encryption": "aes_256_gcm"
        },
        "origin": "external"
    }'
```

The key is created in the `pending_key_material` state, which means it is not yet ready to be used for cryptographic operations.

## Import key material

To import your key material into your Key Manager key, use the `ImportKeyMaterial` [endpoint](https://www.scaleway.com/en/developers/api/key-manager/#path-keys-import-key-material):

```
    curl -X POST 'https://api.scaleway.com/key-manager/v1alpha1/regions/fr-par/keys/<your_key_id>/import-key-material' \
    --header 'Content-Type: application/json' \
    --header 'X-Auth-Token: <Scaleway_API_Secret_Key>' \
    --data '{
        "key_material": "<your_base64_encoded_key_material>",
        "salt": "<your_base64_encoded_salt>"
    }'
```

Execute the following steps to import and use a key:

1. Generate random data locally, which will be used as key material.
2. Create a key with the `external` origin, as described in the [Requirements](#requirements) section.
3. Call `ImportKeyMaterial` with the `key_id` of the key you created, and pass your key material in the `key_material` field.
4. Key Manager uses the key material to create the first key rotation. The key is now ready to use.

<Message type="note">
    Importing key material is only possible while the key is in the `pending_key_material` state, and only for keys using the `AES-256-GCM` algorithm.
</Message>

## Delete key material

To delete the key material of a key, use the `DeleteKeyMaterial` [endpoint](https://www.scaleway.com/en/developers/api/key-manager/#path-keys-delete-key-material):

```
    curl -X POST 'https://api.scaleway.com/key-manager/v1alpha1/regions/fr-par/keys/<your_key_id>/delete-key-material' \
    --header 'Content-Type: application/json' \
    --header 'X-Auth-Token: <Scaleway_API_Secret_Key>' \
    --data '{}'
```

<Message type="important">
    Deleting key material deletes the key rotation that was created with this key material. The key becomes unusable to encrypt or decrypt any payload, and it returns to the `pending_key_material` state. Any ciphertext that was encrypted with this key material can no longer be decrypted.
</Message>

## Rotate an imported key

Rotation for keys with the `external` origin differs from rotation for keys generated by Key Manager. See the [key rotation concept](/key-manager/concepts/#key-rotation) and the [Rotate keys using the Scaleway CLI and API](/key-manager/api-cli/rotate-keys-api-cli/) documentation for more information.

Currently, it is not possible to rotate an imported key by calling `ImportKeyMaterial` a second time on a key that already has key material. Such a call returns a *precondition failed* error, because the key is no longer in the `pending_key_material` state.

The options to "rotate" a BYOK key are:

- Call `DeleteKeyMaterial` to delete the current key rotation, then call `ImportKeyMaterial` again with new key material.
    <Message type="important">
        This is not the same as a regular rotation. In this case, the previous rotation is deleted, and the older ciphertexts can no longer be decrypted with the new key material.
    </Message>
- Create a new key with the `external` origin and import new key material into it, as described in the [Requirements](#requirements) section.