openapi: 3.1.0 info: title: Key Manager API description: |- Scaleway's Key Manager allows you to create, manage and use cryptographic keys in a centralized and secure service. All your cryptographic operations can be delegated to the Key Manager, which in turn ensures the security and availability of your keys. Key Manager supports the following cryptographic operations: data encryption, data decryption, and data encryption key generation. ## Concepts Refer to our [dedicated concepts page](https://www.scaleway.com/en/docs/key-manager/concepts/) to find definitions of the different terms referring to Key Manager. ## Quickstart 1. **Configure your environment variables.** This is an optional step that seeks to simplify your usage of the API. ```bash export SCW_ACCESS_KEY="" export SCW_SECRET_KEY="" export SCW_PROJECT_ID="" ``` 2. **Create a key**. Run the following command to create a key that you can use to encrypt and decrypt your data: ```bash curl "https://api.scaleway.com/key-manager/v1alpha1/regions/$REGION/keys" \ -H "Content-Type: application/json" \ -H "X-Auth-Token: $SCW_SECRET_KEY" \ -d '{ "project_id": "$PROJECT_ID", "name": "my-key", "usage": { "symmetric_encryption": "aes_256_gcm" } }' ``` 3. **Rotate your key**. Run the following command to generate a new version of your key. This operation renders your previous key version obsolete. ```bash curl "https://api.scaleway.com/key-manager/v1alpha1/regions/$REGION/keys//rotate" \ -H "X-Auth-Token: $SCW_SECRET_KEY" \ -d '{ "key_id": "$KEY_ID" }' ``` 4. **Encrypt data**. Run the following command to encrypt data with the key you have created in step 2: ```bash curl "https://api.scaleway.com/key-manager/v1alpha1/regions/$REGION/keys//encrypt" \ -H "X-Auth-Token: $SCW_SECRET_KEY" \ -d '{ "key_id": "$KEY_ID", "plaintext": "'"$(echo -n "plaintext-data" | base64)"'" }' ``` 5. **Generate a data encryption key**. Run the following command to generate a data encryption key that you can use for cryptographic operations outside of Key Manager: ```bash curl "https://api.scaleway.com/key-manager/v1alpha1/regions/$REGION/keys//generate-data-key" \ -H "X-Auth-Token: $SCW_SECRET_KEY" \ -d '{ "key_id": "$KEY_ID", "algorithm": "aes_256_gcm" }' ``` To perform the following steps, you must first ensure that: - You have your [Organization and your Project ID](https://console.scaleway.com/project/settings) - You have a [Scaleway account](https://console.scaleway.com/) - You have created an [API key](https://www.scaleway.com/en/docs/iam/how-to/create-api-keys/) and that the API key has sufficient [IAM permissions](https://www.scaleway.com/en/docs/iam/reference-content/permission-sets/) to perform the actions described on this page - You have [installed `curl`](https://curl.se/download.html) ## Technical information ### Regions Scaleway's infrastructure spans different [regions and Availability Zones](https://www.scaleway.com/en/docs/console/account/reference-content/products-availability/). Key Manager is available in the Paris, Amsterdam and Warsaw regions, which are represented by the following path parameters: - fr-par - nl-ams - pl-waw ## Technical limitations - While Scaleway Key Manager is responsible for generating, encrypting, and decrypting [data encryption keys](https://www.scaleway.com/en/docs/key-manager/concepts/#data-encryption-key-dek/), it does not store, manage, or monitor them, nor does it engage in cryptographic operations with these keys. **You must use and manage data encryption keys outside of Key Manager**. Read our [documentation](https://www.scaleway.com/en/docs/key-manager/reference-content/security-recommendations/) to find out about security measures to be aware of while using Key Manager. ### Symmetric encryption - The maximum payload size that can be encrypted is 64KB of plaintext. - The maximum payload size that can be decrypted is around 131KB of data. - The only symmetric algorithm currently supported by Key Manager is AES-256-GCM. ### Asymmetric encryption - Key Manager supports the following asymmetric encryption algorithms: * RSA-OAEP-2048-SHA256 * RSA-OAEP-3072-SHA256 * RSA-OAEP-4096-SHA256 ### Asymmetric signing - Key Manager supports the following asymmetric signing algorithms: * EC-P256-SHA256 * EC-P384-SHA256 * RSA-PSS-2048-SHA256 * RSA-PSS-3072-SHA256 * RSA-PSS-4096-SHA256 * RSA-PKCS1-2048-SHA256 * RSA-PKCS1-3072-SHA256 * RSA-PKCS1-4096-SHA256 ## Going further For more information about Key Manager, you can check out the following pages: * [Key Manager Documentation](https://www.scaleway.com/en/docs/key-manager/) * [Contact our support team](https://console.scaleway.com/support/tickets). version: v1alpha1 servers: - url: https://api.scaleway.com tags: - name: Keys description: Keys are logical containers you create in Key Manager to store cryptographic keys. They support encryption, decryption, and the generation of data encryption keys. components: schemas: google.protobuf.Int32Value: type: integer format: int32 nullable: true scaleway.key_manager.v1alpha1.DataKey: type: object properties: key_id: type: string description: ID of the data encryption key. (UUID format) example: 6170692e-7363-616c-6577-61792e636f6d algorithm: type: string description: Symmetric encryption algorithm of the data encryption key (`AES-256-GCM`). enum: - unknown_symmetric_encryption - aes_256_gcm x-enum-descriptions: values: aes_256_gcm: Key Manager currently only supports the `AES-GCM` (256-bits) data key algorithm. default: unknown_symmetric_encryption ciphertext: type: string description: |- Data encryption key ciphertext. Your data encryption key's ciphertext can be stored safely. It can only be decrypted through the keys you create in Key Manager, using the relevant key ID. plaintext: type: object description: |- Data encryption key plaintext. (Optional) Your data encryption key's plaintext allows you to use the key immediately upon creation. It must neither be stored or shared. properties: value: type: string x-properties-order: - value created_at: type: string description: Data encryption key creation date. (RFC 3339 format) format: date-time example: "2022-03-22T12:34:56.123456Z" nullable: true x-properties-order: - key_id - algorithm - ciphertext - plaintext - created_at scaleway.key_manager.v1alpha1.DecryptResponse: type: object properties: key_id: type: string description: ID of the key used for decryption. (UUID format) example: 6170692e-7363-616c-6577-61792e636f6d plaintext: type: string description: Key's decrypted data. ciphertext: type: object description: |- (Optional) Data encrypted with the latest key rotation. If the data was already encrypted with the latest key rotation, no output will be returned in the response object. properties: value: type: string x-properties-order: - value x-properties-order: - key_id - plaintext - ciphertext scaleway.key_manager.v1alpha1.EncryptResponse: type: object properties: key_id: type: string description: ID of the key used for encryption. (UUID format) example: 6170692e-7363-616c-6577-61792e636f6d ciphertext: type: string description: Key's encrypted data. x-properties-order: - key_id - ciphertext scaleway.key_manager.v1alpha1.Key: type: object properties: id: type: string description: ID of the key. (UUID format) example: 6170692e-7363-616c-6577-61792e636f6d project_id: type: string description: ID of the Project containing the key. (UUID format) example: 6170692e-7363-616c-6577-61792e636f6d name: type: string description: Name of the key. usage: type: object description: |- Key usage. See the `Key.Usage` enum for a description of possible values. properties: symmetric_encryption: type: string description: |- Encrypt and decrypt arbitrary payloads using a symmetric encryption algorithm. See the `Key.Algorithm.SymmetricEncryption` enum for a description of values. enum: - unknown_symmetric_encryption - aes_256_gcm x-enum-descriptions: values: aes_256_gcm: 256-bit Advanced Encryption Standard (AES-256) keys in Galois Counter Mode (GCM) nullable: true default: unknown_symmetric_encryption x-one-of: usage asymmetric_encryption: type: string description: |- Encrypt and decrypt arbitrary payloads using an asymmetric encryption algorithm. See the `Key.Algorithm.AsymmetricEncryption` enum for a description of values. enum: - unknown_asymmetric_encryption - rsa_oaep_2048_sha256 - rsa_oaep_3072_sha256 - rsa_oaep_4096_sha256 x-enum-descriptions: values: rsa_oaep_2048_sha256: RSA-OAEP (Optimal Asymmetric Encryption Padding) with a 2048-bit key and SHA-256 hash function rsa_oaep_3072_sha256: RSA-OAEP (Optimal Asymmetric Encryption Padding) with a 3072-bit key and SHA-256 hash function (recommended) rsa_oaep_4096_sha256: RSA-OAEP (Optimal Asymmetric Encryption Padding) with a 4096-bit key and SHA-256 hash function nullable: true default: unknown_asymmetric_encryption x-one-of: usage asymmetric_signing: type: string description: |- Sign and verify arbitrary messages using an asymmetric signing algorithm. See the `Key.Algorithm.AsymmetricSigning` enum for a description of values. enum: - unknown_asymmetric_signing - ec_p256_sha256 - ec_p384_sha384 - rsa_pss_2048_sha256 - rsa_pss_3072_sha256 - rsa_pss_4096_sha256 - rsa_pkcs1_2048_sha256 - rsa_pkcs1_3072_sha256 - rsa_pkcs1_4096_sha256 x-enum-descriptions: values: ec_p256_sha256: ECDSA (Elliptic Curve Digital Signature Algorithm) on the P-256 Curve and SHA-256 hash function (recommended) ec_p384_sha384: ECDSA (Elliptic Curve Digital Signature Algorithm) on the P-384 Curve and SHA-384 hash function rsa_pss_2048_sha256: RSA-PSS (Probabilistic Signature Scheme) with a 2048-bit key and SHA-256 hash function rsa_pss_3072_sha256: RSA-PSS (Probabilistic Signature Scheme) with a 3072-bit key and SHA-256 hash function rsa_pss_4096_sha256: RSA-PSS (Probabilistic Signature Scheme) with a 4096-bit key and SHA-256 hash function rsa_pkcs1_2048_sha256: RSA-PKCS1 (Public Key Cryptography Standards) with a 2048-bit key and SHA-256 hash function rsa_pkcs1_3072_sha256: RSA-PKCS1 (Public Key Cryptography Standards) with a 3072-bit key and SHA-256 hash function rsa_pkcs1_4096_sha256: RSA-PKCS1 (Public Key Cryptography Standards) with a 4096-bit key and SHA-256 hash function nullable: true default: unknown_asymmetric_signing x-one-of: usage x-properties-order: - symmetric_encryption - asymmetric_encryption - asymmetric_signing state: type: string description: |- Key state. See the `Key.State` enum for a description of possible values. enum: - unknown_state - enabled - disabled - pending_key_material - scheduled_for_deletion x-enum-descriptions: values: enabled: The key can be used for cryptographic operations. disabled: The key cannot be used for cryptographic operations. pending_key_material: Key material must be imported before the key can be used for cryptographic operations. default: unknown_state rotation_count: type: integer description: |- Number of key rotations. The rotation count tracks the number of times the key has been rotated. format: uint32 created_at: type: string description: Key creation date. (RFC 3339 format) format: date-time example: "2022-03-22T12:34:56.123456Z" nullable: true updated_at: type: string description: Key last modification date. (RFC 3339 format) format: date-time example: "2022-03-22T12:34:56.123456Z" nullable: true protected: type: boolean description: Returns `true` if key protection is applied to the key. locked: type: boolean description: Returns `true` if the key is locked. description: type: string description: Description of the key. nullable: true tags: type: array description: List of the key's tags. items: type: string rotated_at: type: string description: Key last rotation date. (RFC 3339 format) format: date-time example: "2022-03-22T12:34:56.123456Z" nullable: true rotation_policy: type: object description: Key rotation policy. properties: rotation_period: type: string description: |- Rotation period. Time interval between two key rotations. The minimum duration is 24 hours and the maximum duration is 1 year (876000 hours). (in seconds) example: 2.5s nullable: true next_rotation_at: type: string description: |- Key next rotation date. Timestamp indicating the next scheduled rotation. (RFC 3339 format) format: date-time example: "2022-03-22T12:34:56.123456Z" nullable: true x-properties-order: - rotation_period - next_rotation_at origin: type: string description: |- Key origin. Refer to the `Key.Origin` enum for a description of values. enum: - unknown_origin - scaleway_kms - external x-enum-descriptions: values: scaleway_kms: Key Manager generates the key material upon key creation external: Key Manager creates a key with key material coming from an external source default: unknown_origin deletion_requested_at: type: string description: Returns the time at which deletion was requested. (RFC 3339 format) format: date-time example: "2022-03-22T12:34:56.123456Z" nullable: true region: type: string description: Region where the key is stored. x-properties-order: - id - project_id - name - usage - state - rotation_count - created_at - updated_at - protected - locked - description - tags - rotated_at - rotation_policy - origin - deletion_requested_at - region scaleway.key_manager.v1alpha1.ListAlgorithmsRequest.Usage: type: string enum: - unknown_usage - symmetric_encryption - asymmetric_encryption - asymmetric_signing default: unknown_usage scaleway.key_manager.v1alpha1.ListAlgorithmsResponse: type: object properties: algorithms: type: array description: Returns a list of algorithms matching the requested criteria. items: $ref: '#/components/schemas/scaleway.key_manager.v1alpha1.ListAlgorithmsResponse.Algorithm' x-properties-order: - algorithms scaleway.key_manager.v1alpha1.ListAlgorithmsResponse.Algorithm: type: object properties: usage: type: string name: type: string recommended: type: boolean x-properties-order: - usage - name - recommended scaleway.key_manager.v1alpha1.ListKeysRequest.OrderBy: type: string enum: - name_asc - name_desc - created_at_asc - created_at_desc - updated_at_asc - updated_at_desc default: name_asc scaleway.key_manager.v1alpha1.ListKeysResponse: type: object properties: keys: type: array description: Single page of keys matching the requested criteria. items: $ref: '#/components/schemas/scaleway.key_manager.v1alpha1.Key' total_count: type: integer description: Total count of keys matching the requested criteria. format: uint64 x-properties-order: - keys - total_count scaleway.key_manager.v1alpha1.PublicKey: type: object properties: pem: type: string x-properties-order: - pem scaleway.key_manager.v1alpha1.SignResponse: type: object properties: key_id: type: string description: ID of the key used to generate the signature. (UUID format) example: 6170692e-7363-616c-6577-61792e636f6d signature: type: string description: The message signature. x-properties-order: - key_id - signature scaleway.key_manager.v1alpha1.VerifyResponse: type: object properties: key_id: type: string description: ID of the key used for verification. (UUID format) example: 6170692e-7363-616c-6577-61792e636f6d valid: type: boolean description: |- Defines whether the signature is valid. Returns `true` if the signature is valid for the digest and key, and `false` otherwise. x-properties-order: - key_id - valid securitySchemes: scaleway: in: header name: X-Auth-Token type: apiKey paths: /key-manager/v1alpha1/regions/{region}/algorithms: get: tags: - Keys operationId: ListAlgorithms summary: List all available algorithms description: Lists all cryptographic algorithms supported by the Key Manager service. parameters: - in: path name: region description: The region you want to target required: true schema: type: string enum: - fr-par - nl-ams - pl-waw - in: query name: usages description: Filter by key usage. schema: type: array items: $ref: '#/components/schemas/scaleway.key_manager.v1alpha1.ListAlgorithmsRequest.Usage' responses: "200": description: "" content: application/json: schema: $ref: '#/components/schemas/scaleway.key_manager.v1alpha1.ListAlgorithmsResponse' security: - scaleway: [] x-codeSamples: - lang: cURL source: |- curl -X GET \ -H "X-Auth-Token: $SCW_SECRET_KEY" \ "https://api.scaleway.com/key-manager/v1alpha1/regions/{region}/algorithms" - lang: HTTPie source: |- http GET "https://api.scaleway.com/key-manager/v1alpha1/regions/{region}/algorithms" \ X-Auth-Token:$SCW_SECRET_KEY /key-manager/v1alpha1/regions/{region}/keys: get: tags: - Keys operationId: ListKeys summary: List keys description: Retrieve a list of keys across all Projects in an Organization or within a specific Project. You must specify the `region`, and either the `organization_id` or the `project_id`. parameters: - in: path name: region description: The region you want to target required: true schema: type: string enum: - fr-par - nl-ams - pl-waw - in: query name: organization_id description: (Optional) Filter by Organization ID. (UUID format) schema: type: string example: 6170692e-7363-616c-6577-61792e636f6d - in: query name: project_id description: (Optional) Filter by Project ID. (UUID format) schema: type: string example: 6170692e-7363-616c-6577-61792e636f6d - in: query name: order_by schema: $ref: '#/components/schemas/scaleway.key_manager.v1alpha1.ListKeysRequest.OrderBy' - in: query name: page schema: $ref: '#/components/schemas/google.protobuf.Int32Value' - in: query name: page_size schema: type: integer format: uint32 - in: query name: tags description: (Optional) List of tags to filter on. schema: type: array items: type: string - in: query name: name description: (Optional) Filter by key name. schema: type: string - in: query name: usage description: |- (Optional) Filter keys by usage. Select from symmetric encryption, asymmetric encryption, or asymmetric signing. schema: type: string enum: - unknown_usage - symmetric_encryption - asymmetric_encryption - asymmetric_signing default: unknown_usage - in: query name: scheduled_for_deletion description: Filter keys based on their deletion status. By default, only keys not scheduled for deletion are returned in the output. required: true schema: type: boolean responses: "200": description: "" content: application/json: schema: $ref: '#/components/schemas/scaleway.key_manager.v1alpha1.ListKeysResponse' security: - scaleway: [] x-codeSamples: - lang: cURL source: |- curl -X GET \ -H "X-Auth-Token: $SCW_SECRET_KEY" \ "https://api.scaleway.com/key-manager/v1alpha1/regions/{region}/keys?scheduled_for_deletion=false" - lang: HTTPie source: |- http GET "https://api.scaleway.com/key-manager/v1alpha1/regions/{region}/keys" \ X-Auth-Token:$SCW_SECRET_KEY \ scheduled_for_deletion==false post: tags: - Keys operationId: CreateKey summary: Create a key description: Create a key in a given region specified by the `region` parameter. You can use keys to encrypt or decrypt arbitrary payloads, to sign and verify messages or to generate data encryption keys. **Data encryption keys are not stored in Key Manager**. parameters: - in: path name: region description: The region you want to target required: true schema: type: string enum: - fr-par - nl-ams - pl-waw responses: "200": description: "" content: application/json: schema: $ref: '#/components/schemas/scaleway.key_manager.v1alpha1.Key' requestBody: required: true content: application/json: schema: type: object properties: project_id: type: string description: ID of the Project containing the key. (UUID format) example: 6170692e-7363-616c-6577-61792e636f6d name: type: string description: (Optional) Name of the key. nullable: true usage: type: object description: |- Key usage. See the `Key.Usage` enum for a description of possible values. properties: symmetric_encryption: type: string description: |- Encrypt and decrypt arbitrary payloads using a symmetric encryption algorithm. See the `Key.Algorithm.SymmetricEncryption` enum for a description of values. enum: - unknown_symmetric_encryption - aes_256_gcm x-enum-descriptions: values: aes_256_gcm: 256-bit Advanced Encryption Standard (AES-256) keys in Galois Counter Mode (GCM) nullable: true default: unknown_symmetric_encryption x-one-of: usage asymmetric_encryption: type: string description: |- Encrypt and decrypt arbitrary payloads using an asymmetric encryption algorithm. See the `Key.Algorithm.AsymmetricEncryption` enum for a description of values. enum: - unknown_asymmetric_encryption - rsa_oaep_2048_sha256 - rsa_oaep_3072_sha256 - rsa_oaep_4096_sha256 x-enum-descriptions: values: rsa_oaep_2048_sha256: RSA-OAEP (Optimal Asymmetric Encryption Padding) with a 2048-bit key and SHA-256 hash function rsa_oaep_3072_sha256: RSA-OAEP (Optimal Asymmetric Encryption Padding) with a 3072-bit key and SHA-256 hash function (recommended) rsa_oaep_4096_sha256: RSA-OAEP (Optimal Asymmetric Encryption Padding) with a 4096-bit key and SHA-256 hash function nullable: true default: unknown_asymmetric_encryption x-one-of: usage asymmetric_signing: type: string description: |- Sign and verify arbitrary messages using an asymmetric signing algorithm. See the `Key.Algorithm.AsymmetricSigning` enum for a description of values. enum: - unknown_asymmetric_signing - ec_p256_sha256 - ec_p384_sha384 - rsa_pss_2048_sha256 - rsa_pss_3072_sha256 - rsa_pss_4096_sha256 - rsa_pkcs1_2048_sha256 - rsa_pkcs1_3072_sha256 - rsa_pkcs1_4096_sha256 x-enum-descriptions: values: ec_p256_sha256: ECDSA (Elliptic Curve Digital Signature Algorithm) on the P-256 Curve and SHA-256 hash function (recommended) ec_p384_sha384: ECDSA (Elliptic Curve Digital Signature Algorithm) on the P-384 Curve and SHA-384 hash function rsa_pss_2048_sha256: RSA-PSS (Probabilistic Signature Scheme) with a 2048-bit key and SHA-256 hash function rsa_pss_3072_sha256: RSA-PSS (Probabilistic Signature Scheme) with a 3072-bit key and SHA-256 hash function rsa_pss_4096_sha256: RSA-PSS (Probabilistic Signature Scheme) with a 4096-bit key and SHA-256 hash function rsa_pkcs1_2048_sha256: RSA-PKCS1 (Public Key Cryptography Standards) with a 2048-bit key and SHA-256 hash function rsa_pkcs1_3072_sha256: RSA-PKCS1 (Public Key Cryptography Standards) with a 3072-bit key and SHA-256 hash function rsa_pkcs1_4096_sha256: RSA-PKCS1 (Public Key Cryptography Standards) with a 4096-bit key and SHA-256 hash function nullable: true default: unknown_asymmetric_signing x-one-of: usage x-properties-order: - symmetric_encryption - asymmetric_encryption - asymmetric_signing description: type: string description: (Optional) Description of the key. nullable: true tags: type: array description: (Optional) List of the key's tags. items: type: string rotation_policy: type: object description: |- (Optional) Rotation policy of the key. If not specified, no rotation policy will be applied to the key. properties: rotation_period: type: string description: |- Rotation period. Time interval between two key rotations. The minimum duration is 24 hours and the maximum duration is 1 year (876000 hours). (in seconds) example: 2.5s nullable: true next_rotation_at: type: string description: |- Key next rotation date. Timestamp indicating the next scheduled rotation. (RFC 3339 format) format: date-time example: "2022-03-22T12:34:56.123456Z" nullable: true x-properties-order: - rotation_period - next_rotation_at unprotected: type: boolean description: |- (Optional) Defines whether key protection is applied to a key. Protected keys can be used but not deleted. Default value is `false`. origin: type: string description: |- Key origin. Refer to the `Key.Origin` enum for a description of values. enum: - unknown_origin - scaleway_kms - external x-enum-descriptions: values: scaleway_kms: Key Manager generates the key material upon key creation external: Key Manager creates a key with key material coming from an external source default: unknown_origin x-properties-order: - project_id - name - usage - description - tags - rotation_policy - unprotected - origin security: - scaleway: [] x-codeSamples: - lang: cURL source: |- curl -X POST \ -H "X-Auth-Token: $SCW_SECRET_KEY" \ -H "Content-Type: application/json" \ -d '{"project_id":"6170692e-7363-616c-6577-61792e636f6d","unprotected":false}' \ "https://api.scaleway.com/key-manager/v1alpha1/regions/{region}/keys" - lang: HTTPie source: |- http POST "https://api.scaleway.com/key-manager/v1alpha1/regions/{region}/keys" \ X-Auth-Token:$SCW_SECRET_KEY \ project_id="6170692e-7363-616c-6577-61792e636f6d" \ unprotected:=false /key-manager/v1alpha1/regions/{region}/keys/{key_id}: get: tags: - Keys operationId: GetKey summary: Get key metadata description: Retrieve metadata for a specified key using the `region` and `key_id` parameters. parameters: - in: path name: region description: The region you want to target required: true schema: type: string enum: - fr-par - nl-ams - pl-waw - in: path name: key_id description: ID of the key to target. (UUID format) required: true schema: type: string example: 6170692e-7363-616c-6577-61792e636f6d responses: "200": description: "" content: application/json: schema: $ref: '#/components/schemas/scaleway.key_manager.v1alpha1.Key' security: - scaleway: [] x-codeSamples: - lang: cURL source: |- curl -X GET \ -H "X-Auth-Token: $SCW_SECRET_KEY" \ "https://api.scaleway.com/key-manager/v1alpha1/regions/{region}/keys/{key_id}" - lang: HTTPie source: |- http GET "https://api.scaleway.com/key-manager/v1alpha1/regions/{region}/keys/{key_id}" \ X-Auth-Token:$SCW_SECRET_KEY patch: tags: - Keys operationId: UpdateKey summary: Update a key description: Modify a key's metadata including name, description and tags, specified by the `key_id` and `region` parameters. parameters: - in: path name: region description: The region you want to target required: true schema: type: string enum: - fr-par - nl-ams - pl-waw - in: path name: key_id description: ID of the key to update. (UUID format) required: true schema: type: string example: 6170692e-7363-616c-6577-61792e636f6d responses: "200": description: "" content: application/json: schema: $ref: '#/components/schemas/scaleway.key_manager.v1alpha1.Key' requestBody: required: true content: application/json: schema: type: object properties: name: type: string description: (Optional) Updated name of the key. nullable: true description: type: string description: (Optional) Updated description of the key. nullable: true tags: type: array description: (Optional) Updated list of the key's tags. nullable: true items: type: string rotation_policy: type: object description: |- (Optional) Updated rotation policy of the key. If not specified, the key's existing rotation policy applies. properties: rotation_period: type: string description: |- Rotation period. Time interval between two key rotations. The minimum duration is 24 hours and the maximum duration is 1 year (876000 hours). (in seconds) example: 2.5s nullable: true next_rotation_at: type: string description: |- Key next rotation date. Timestamp indicating the next scheduled rotation. (RFC 3339 format) format: date-time example: "2022-03-22T12:34:56.123456Z" nullable: true x-properties-order: - rotation_period - next_rotation_at x-properties-order: - name - description - tags - rotation_policy security: - scaleway: [] x-codeSamples: - lang: cURL source: |- curl -X PATCH \ -H "X-Auth-Token: $SCW_SECRET_KEY" \ -H "Content-Type: application/json" \ -d '{}' \ "https://api.scaleway.com/key-manager/v1alpha1/regions/{region}/keys/{key_id}" - lang: HTTPie source: |- http PATCH "https://api.scaleway.com/key-manager/v1alpha1/regions/{region}/keys/{key_id}" \ X-Auth-Token:$SCW_SECRET_KEY delete: tags: - Keys operationId: DeleteKey summary: Delete a key description: Permanently delete a key specified by the `region` and `key_id` parameters. This action is irreversible. Any data encrypted with this key, including data encryption keys, will no longer be decipherable. parameters: - in: path name: region description: The region you want to target required: true schema: type: string enum: - fr-par - nl-ams - pl-waw - in: path name: key_id description: ID of the key to delete. (UUID format) required: true schema: type: string example: 6170692e-7363-616c-6577-61792e636f6d responses: "204": description: "" security: - scaleway: [] x-codeSamples: - lang: cURL source: |- curl -X DELETE \ -H "X-Auth-Token: $SCW_SECRET_KEY" \ "https://api.scaleway.com/key-manager/v1alpha1/regions/{region}/keys/{key_id}" - lang: HTTPie source: |- http DELETE "https://api.scaleway.com/key-manager/v1alpha1/regions/{region}/keys/{key_id}" \ X-Auth-Token:$SCW_SECRET_KEY /key-manager/v1alpha1/regions/{region}/keys/{key_id}/decrypt: post: tags: - Keys operationId: Decrypt summary: Decrypt an encrypted payload description: Decrypt an encrypted payload using an existing key, specified by the `key_id` parameter. The maximum payload size that can be decrypted is equivalent to the encrypted output of 64 KB of data (around 131 KB). parameters: - in: path name: region description: The region you want to target required: true schema: type: string enum: - fr-par - nl-ams - pl-waw - in: path name: key_id description: |- ID of the key to decrypt with. The key must have an usage set to `symmetric_encryption` or `asymmetric_encryption`. (UUID format) required: true schema: type: string example: 6170692e-7363-616c-6577-61792e636f6d responses: "200": description: "" content: application/json: schema: $ref: '#/components/schemas/scaleway.key_manager.v1alpha1.DecryptResponse' requestBody: required: true content: application/json: schema: type: object properties: ciphertext: type: string description: |- Ciphertext data to decrypt. Data size must be between 1 and 131071 bytes. associated_data: type: object description: |- (Optional) Additional authenticated data. The additional data must match the value passed in the encryption request. Only supported by keys with a usage set to `symmetric_encryption`. properties: value: type: string x-properties-order: - value x-properties-order: - ciphertext - associated_data security: - scaleway: [] x-codeSamples: - lang: cURL source: |- curl -X POST \ -H "X-Auth-Token: $SCW_SECRET_KEY" \ -H "Content-Type: application/json" \ -d '{"ciphertext":"string"}' \ "https://api.scaleway.com/key-manager/v1alpha1/regions/{region}/keys/{key_id}/decrypt" - lang: HTTPie source: |- http POST "https://api.scaleway.com/key-manager/v1alpha1/regions/{region}/keys/{key_id}/decrypt" \ X-Auth-Token:$SCW_SECRET_KEY \ ciphertext="string" /key-manager/v1alpha1/regions/{region}/keys/{key_id}/delete-key-material: post: tags: - Keys operationId: DeleteKeyMaterial summary: Delete key material description: Delete previously imported key material. This renders the associated cryptographic key unusable for any operation. The key's origin must be `external`. parameters: - in: path name: region description: The region you want to target required: true schema: type: string enum: - fr-par - nl-ams - pl-waw - in: path name: key_id description: ID of the key of which to delete the key material. (UUID format) required: true schema: type: string example: 6170692e-7363-616c-6577-61792e636f6d responses: "204": description: "" requestBody: required: true content: application/json: schema: type: object security: - scaleway: [] x-codeSamples: - lang: cURL source: |- curl -X POST \ -H "X-Auth-Token: $SCW_SECRET_KEY" \ -H "Content-Type: application/json" \ -d '{}' \ "https://api.scaleway.com/key-manager/v1alpha1/regions/{region}/keys/{key_id}/delete-key-material" - lang: HTTPie source: |- http POST "https://api.scaleway.com/key-manager/v1alpha1/regions/{region}/keys/{key_id}/delete-key-material" \ X-Auth-Token:$SCW_SECRET_KEY /key-manager/v1alpha1/regions/{region}/keys/{key_id}/disable: post: tags: - Keys operationId: DisableKey summary: Disable key description: Disable a given key, preventing it to be used for cryptographic operations. Disabling a key renders it unusable. You must specify the `region` and `key_id` parameters. parameters: - in: path name: region description: The region you want to target required: true schema: type: string enum: - fr-par - nl-ams - pl-waw - in: path name: key_id description: ID of the key to disable. (UUID format) required: true schema: type: string example: 6170692e-7363-616c-6577-61792e636f6d responses: "200": description: "" content: application/json: schema: $ref: '#/components/schemas/scaleway.key_manager.v1alpha1.Key' requestBody: required: true content: application/json: schema: type: object security: - scaleway: [] x-codeSamples: - lang: cURL source: |- curl -X POST \ -H "X-Auth-Token: $SCW_SECRET_KEY" \ -H "Content-Type: application/json" \ -d '{}' \ "https://api.scaleway.com/key-manager/v1alpha1/regions/{region}/keys/{key_id}/disable" - lang: HTTPie source: |- http POST "https://api.scaleway.com/key-manager/v1alpha1/regions/{region}/keys/{key_id}/disable" \ X-Auth-Token:$SCW_SECRET_KEY /key-manager/v1alpha1/regions/{region}/keys/{key_id}/enable: post: tags: - Keys operationId: EnableKey summary: Enable key description: Enable a given key to be used for cryptographic operations. Enabling a key allows you to make a disabled key usable again. You must specify the `region` and `key_id` parameters. parameters: - in: path name: region description: The region you want to target required: true schema: type: string enum: - fr-par - nl-ams - pl-waw - in: path name: key_id description: ID of the key to enable. (UUID format) required: true schema: type: string example: 6170692e-7363-616c-6577-61792e636f6d responses: "200": description: "" content: application/json: schema: $ref: '#/components/schemas/scaleway.key_manager.v1alpha1.Key' requestBody: required: true content: application/json: schema: type: object security: - scaleway: [] x-codeSamples: - lang: cURL source: |- curl -X POST \ -H "X-Auth-Token: $SCW_SECRET_KEY" \ -H "Content-Type: application/json" \ -d '{}' \ "https://api.scaleway.com/key-manager/v1alpha1/regions/{region}/keys/{key_id}/enable" - lang: HTTPie source: |- http POST "https://api.scaleway.com/key-manager/v1alpha1/regions/{region}/keys/{key_id}/enable" \ X-Auth-Token:$SCW_SECRET_KEY /key-manager/v1alpha1/regions/{region}/keys/{key_id}/encrypt: post: tags: - Keys operationId: Encrypt summary: Encrypt a payload description: Encrypt a payload using an existing key, specified by the `key_id` parameter. The maximum payload size that can be encrypted is 64 KB of plaintext. parameters: - in: path name: region description: The region you want to target required: true schema: type: string enum: - fr-par - nl-ams - pl-waw - in: path name: key_id description: |- ID of the key to use for encryption. The key must have an usage set to `symmetric_encryption` or `asymmetric_encryption`. (UUID format) required: true schema: type: string example: 6170692e-7363-616c-6577-61792e636f6d responses: "200": description: "" content: application/json: schema: $ref: '#/components/schemas/scaleway.key_manager.v1alpha1.EncryptResponse' requestBody: required: true content: application/json: schema: type: object properties: plaintext: type: string description: |- Plaintext data to encrypt. Data size must be between 1 and 65535 bytes. associated_data: type: object description: |- (Optional) Additional authenticated data. Additional data which will not be encrypted, but authenticated and appended to the encrypted payload. Only supported by keys with a usage set to `symmetric_encryption`. properties: value: type: string x-properties-order: - value x-properties-order: - plaintext - associated_data security: - scaleway: [] x-codeSamples: - lang: cURL source: |- curl -X POST \ -H "X-Auth-Token: $SCW_SECRET_KEY" \ -H "Content-Type: application/json" \ -d '{"plaintext":"string"}' \ "https://api.scaleway.com/key-manager/v1alpha1/regions/{region}/keys/{key_id}/encrypt" - lang: HTTPie source: |- http POST "https://api.scaleway.com/key-manager/v1alpha1/regions/{region}/keys/{key_id}/encrypt" \ X-Auth-Token:$SCW_SECRET_KEY \ plaintext="string" /key-manager/v1alpha1/regions/{region}/keys/{key_id}/generate-data-key: post: tags: - Keys operationId: GenerateDataKey summary: Create a data encryption key description: |- Create a new data encryption key for cryptographic operations outside of Key Manager. The data encryption key is encrypted and must be decrypted using the key you have created in Key Manager. The data encryption key is returned in plaintext and ciphertext but it should only be stored in its encrypted form (ciphertext). Key Manager does not store your data encryption key. To retrieve your key's plaintext, use the `Decrypt` method with your key's ID and ciphertext. parameters: - in: path name: region description: The region you want to target required: true schema: type: string enum: - fr-par - nl-ams - pl-waw - in: path name: key_id description: ID of the key. (UUID format) required: true schema: type: string example: 6170692e-7363-616c-6577-61792e636f6d responses: "200": description: "" content: application/json: schema: $ref: '#/components/schemas/scaleway.key_manager.v1alpha1.DataKey' requestBody: required: true content: application/json: schema: type: object properties: algorithm: type: string description: |- Algorithm with which the data encryption key will be used to encrypt and decrypt arbitrary payloads. See the `DataKey.Algorithm.SymmetricEncryption` enum for a description of values. enum: - unknown_symmetric_encryption - aes_256_gcm x-enum-descriptions: values: aes_256_gcm: Key Manager currently only supports the `AES-GCM` (256-bits) data key algorithm. default: unknown_symmetric_encryption without_plaintext: type: boolean description: |- (Optional) Defines whether to return the data encryption key's plaintext in the response object. Default value is `false`, meaning that the plaintext is returned. Set it to `true` if you do not wish the plaintext to be returned in the response object. x-properties-order: - algorithm - without_plaintext security: - scaleway: [] x-codeSamples: - lang: cURL source: |- curl -X POST \ -H "X-Auth-Token: $SCW_SECRET_KEY" \ -H "Content-Type: application/json" \ -d '{"without_plaintext":false}' \ "https://api.scaleway.com/key-manager/v1alpha1/regions/{region}/keys/{key_id}/generate-data-key" - lang: HTTPie source: |- http POST "https://api.scaleway.com/key-manager/v1alpha1/regions/{region}/keys/{key_id}/generate-data-key" \ X-Auth-Token:$SCW_SECRET_KEY \ without_plaintext:=false /key-manager/v1alpha1/regions/{region}/keys/{key_id}/import-key-material: post: tags: - Keys operationId: ImportKeyMaterial summary: Import key material description: Import externally generated key material into Key Manager to derive a new cryptographic key. The key's origin must be `external`. parameters: - in: path name: region description: The region you want to target required: true schema: type: string enum: - fr-par - nl-ams - pl-waw - in: path name: key_id description: |- ID of the key in which to import key material. The key's origin must be `external`. (UUID format) required: true schema: type: string example: 6170692e-7363-616c-6577-61792e636f6d responses: "200": description: "" content: application/json: schema: $ref: '#/components/schemas/scaleway.key_manager.v1alpha1.Key' requestBody: required: true content: application/json: schema: type: object properties: key_material: type: string description: The key material The key material is a random sequence of bytes used to derive a cryptographic key. salt: type: object description: |- (Optional) Salt value to pass the key derivation function. A salt is random data added to key material to ensure unique derived keys, even if the input is similar. It helps strengthen security when the key material has low randomness (low entropy). properties: value: type: string x-properties-order: - value x-properties-order: - key_material - salt security: - scaleway: [] x-codeSamples: - lang: cURL source: |- curl -X POST \ -H "X-Auth-Token: $SCW_SECRET_KEY" \ -H "Content-Type: application/json" \ -d '{"key_material":"string"}' \ "https://api.scaleway.com/key-manager/v1alpha1/regions/{region}/keys/{key_id}/import-key-material" - lang: HTTPie source: |- http POST "https://api.scaleway.com/key-manager/v1alpha1/regions/{region}/keys/{key_id}/import-key-material" \ X-Auth-Token:$SCW_SECRET_KEY \ key_material="string" /key-manager/v1alpha1/regions/{region}/keys/{key_id}/protect: post: tags: - Keys operationId: ProtectKey summary: Apply key protection description: Apply protection to a given key specified by the `key_id` parameter. Applying key protection means that your key can be used and modified, but it cannot be deleted. parameters: - in: path name: region description: The region you want to target required: true schema: type: string enum: - fr-par - nl-ams - pl-waw - in: path name: key_id description: ID of the key to apply key protection to. (UUID format) required: true schema: type: string example: 6170692e-7363-616c-6577-61792e636f6d responses: "200": description: "" content: application/json: schema: $ref: '#/components/schemas/scaleway.key_manager.v1alpha1.Key' requestBody: required: true content: application/json: schema: type: object security: - scaleway: [] x-codeSamples: - lang: cURL source: |- curl -X POST \ -H "X-Auth-Token: $SCW_SECRET_KEY" \ -H "Content-Type: application/json" \ -d '{}' \ "https://api.scaleway.com/key-manager/v1alpha1/regions/{region}/keys/{key_id}/protect" - lang: HTTPie source: |- http POST "https://api.scaleway.com/key-manager/v1alpha1/regions/{region}/keys/{key_id}/protect" \ X-Auth-Token:$SCW_SECRET_KEY /key-manager/v1alpha1/regions/{region}/keys/{key_id}/public-key: get: tags: - Keys operationId: GetPublicKey summary: Get the public key in PEM format. description: Retrieves the public portion of an asymmetric cryptographic key in PEM format. parameters: - in: path name: region description: The region you want to target required: true schema: type: string enum: - fr-par - nl-ams - pl-waw - in: path name: key_id description: ID of the key. (UUID format) required: true schema: type: string example: 6170692e-7363-616c-6577-61792e636f6d responses: "200": description: "" content: application/json: schema: $ref: '#/components/schemas/scaleway.key_manager.v1alpha1.PublicKey' security: - scaleway: [] x-codeSamples: - lang: cURL source: |- curl -X GET \ -H "X-Auth-Token: $SCW_SECRET_KEY" \ "https://api.scaleway.com/key-manager/v1alpha1/regions/{region}/keys/{key_id}/public-key" - lang: HTTPie source: |- http GET "https://api.scaleway.com/key-manager/v1alpha1/regions/{region}/keys/{key_id}/public-key" \ X-Auth-Token:$SCW_SECRET_KEY /key-manager/v1alpha1/regions/{region}/keys/{key_id}/restore: post: tags: - Keys operationId: RestoreKey summary: Restore a key description: Restore a key and all its rotations scheduled for deletion specified by the `region` and `key_id` parameters. parameters: - in: path name: region description: The region you want to target required: true schema: type: string enum: - fr-par - nl-ams - pl-waw - in: path name: key_id required: true schema: type: string responses: "200": description: "" content: application/json: schema: $ref: '#/components/schemas/scaleway.key_manager.v1alpha1.Key' requestBody: required: true content: application/json: schema: type: object security: - scaleway: [] x-codeSamples: - lang: cURL source: |- curl -X POST \ -H "X-Auth-Token: $SCW_SECRET_KEY" \ -H "Content-Type: application/json" \ -d '{}' \ "https://api.scaleway.com/key-manager/v1alpha1/regions/{region}/keys/{key_id}/restore" - lang: HTTPie source: |- http POST "https://api.scaleway.com/key-manager/v1alpha1/regions/{region}/keys/{key_id}/restore" \ X-Auth-Token:$SCW_SECRET_KEY /key-manager/v1alpha1/regions/{region}/keys/{key_id}/rotate: post: tags: - Keys operationId: RotateKey summary: Rotate a key description: Generate a new version of an existing key with new key material. Previous key versions remain usable to decrypt previously encrypted data, but the key's new version will be used for subsequent encryption operations and data key generation. parameters: - in: path name: region description: The region you want to target required: true schema: type: string enum: - fr-par - nl-ams - pl-waw - in: path name: key_id description: ID of the key to rotate. (UUID format) required: true schema: type: string example: 6170692e-7363-616c-6577-61792e636f6d responses: "200": description: "" content: application/json: schema: $ref: '#/components/schemas/scaleway.key_manager.v1alpha1.Key' requestBody: required: true content: application/json: schema: type: object security: - scaleway: [] x-codeSamples: - lang: cURL source: |- curl -X POST \ -H "X-Auth-Token: $SCW_SECRET_KEY" \ -H "Content-Type: application/json" \ -d '{}' \ "https://api.scaleway.com/key-manager/v1alpha1/regions/{region}/keys/{key_id}/rotate" - lang: HTTPie source: |- http POST "https://api.scaleway.com/key-manager/v1alpha1/regions/{region}/keys/{key_id}/rotate" \ X-Auth-Token:$SCW_SECRET_KEY /key-manager/v1alpha1/regions/{region}/keys/{key_id}/sign: post: tags: - Keys operationId: Sign summary: Sign a message digest description: Use a given key to sign a message digest. The key must have its usage set to `asymmetric_signing`. The digest must be created using the same digest algorithm that is defined in the key's algorithm configuration. parameters: - in: path name: region description: The region you want to target required: true schema: type: string enum: - fr-par - nl-ams - pl-waw - in: path name: key_id description: ID of the key to use for signing. (UUID format) required: true schema: type: string example: 6170692e-7363-616c-6577-61792e636f6d responses: "200": description: "" content: application/json: schema: $ref: '#/components/schemas/scaleway.key_manager.v1alpha1.SignResponse' requestBody: required: true content: application/json: schema: type: object properties: digest: type: string description: |- Digest of the message to sign. The digest must be generated using the same algorithm defined in the key’s algorithm settings. x-properties-order: - digest security: - scaleway: [] x-codeSamples: - lang: cURL source: |- curl -X POST \ -H "X-Auth-Token: $SCW_SECRET_KEY" \ -H "Content-Type: application/json" \ -d '{"digest":"string"}' \ "https://api.scaleway.com/key-manager/v1alpha1/regions/{region}/keys/{key_id}/sign" - lang: HTTPie source: |- http POST "https://api.scaleway.com/key-manager/v1alpha1/regions/{region}/keys/{key_id}/sign" \ X-Auth-Token:$SCW_SECRET_KEY \ digest="string" /key-manager/v1alpha1/regions/{region}/keys/{key_id}/unprotect: post: tags: - Keys operationId: UnprotectKey summary: Remove key protection description: Remove key protection from a given key specified by the `key_id` parameter. Removing key protection means that your key can be deleted anytime. parameters: - in: path name: region description: The region you want to target required: true schema: type: string enum: - fr-par - nl-ams - pl-waw - in: path name: key_id description: ID of the key to remove key protection from. (UUID format) required: true schema: type: string example: 6170692e-7363-616c-6577-61792e636f6d responses: "200": description: "" content: application/json: schema: $ref: '#/components/schemas/scaleway.key_manager.v1alpha1.Key' requestBody: required: true content: application/json: schema: type: object security: - scaleway: [] x-codeSamples: - lang: cURL source: |- curl -X POST \ -H "X-Auth-Token: $SCW_SECRET_KEY" \ -H "Content-Type: application/json" \ -d '{}' \ "https://api.scaleway.com/key-manager/v1alpha1/regions/{region}/keys/{key_id}/unprotect" - lang: HTTPie source: |- http POST "https://api.scaleway.com/key-manager/v1alpha1/regions/{region}/keys/{key_id}/unprotect" \ X-Auth-Token:$SCW_SECRET_KEY /key-manager/v1alpha1/regions/{region}/keys/{key_id}/verify: post: tags: - Keys operationId: Verify summary: Verify a message signature description: Use a given key to verify a message signature against a message digest. The key must have its usage set to `asymmetric_signing`. The message digest must be generated using the same digest algorithm that is defined in the key's algorithm configuration. parameters: - in: path name: region description: The region you want to target required: true schema: type: string enum: - fr-par - nl-ams - pl-waw - in: path name: key_id description: ID of the key to use for signature verification. (UUID format) required: true schema: type: string example: 6170692e-7363-616c-6577-61792e636f6d responses: "200": description: "" content: application/json: schema: $ref: '#/components/schemas/scaleway.key_manager.v1alpha1.VerifyResponse' requestBody: required: true content: application/json: schema: type: object properties: digest: type: string description: |- Digest of the original signed message. Must be generated using the same algorithm specified in the key’s configuration. signature: type: string description: The message signature to verify. x-properties-order: - digest - signature security: - scaleway: [] x-codeSamples: - lang: cURL source: |- curl -X POST \ -H "X-Auth-Token: $SCW_SECRET_KEY" \ -H "Content-Type: application/json" \ -d '{"digest":"string","signature":"string"}' \ "https://api.scaleway.com/key-manager/v1alpha1/regions/{region}/keys/{key_id}/verify" - lang: HTTPie source: |- http POST "https://api.scaleway.com/key-manager/v1alpha1/regions/{region}/keys/{key_id}/verify" \ X-Auth-Token:$SCW_SECRET_KEY \ digest="string" \ signature="string"