A key alias is a human-readable name you can use in place of a key ID when calling Key Management Service (KMS) operations. For example, alias/my-app-key is easier to reference and manage across environments than 08ec3bb9-034f-485b-b1cd-3459baa8****.
An alias is an independent resource — actions on an alias do not affect the associated key. You can reassign an alias to a different key, or delete an alias entirely, without affecting the key.
Alias rules and constraints
| Rule | Details |
|---|---|
| Required prefix | alias/ |
| Name length (excluding prefix) | 1–255 characters |
| Allowed characters | Letters, digits, underscores (_), hyphens (-), and forward slashes (/) |
| Reserved format | alias/acs/<service> — reserved by KMS for service keys (for example, alias/acs/oss). Do not use this format for custom aliases. |
| Uniqueness | Unique within a region under the same Alibaba Cloud account. The same alias name can exist in different regions. |
| Key-to-alias relationship | A key can have multiple aliases. Each alias is associated with exactly one key. |
| Modifying an alias | Aliases cannot be modified. To modify the alias of a key, create a new alias for the key, then delete the original. |
| Deleting an alias | Deleting an alias does not delete the associated key. |
| RAM permissions | When a Resource Access Management (RAM) user performs operations using an alias, they need permissions on the key — not the alias. |
Before deleting an alias, confirm it is no longer in use. If your application still references the alias, deleting it may cause data encryption to fail.
Create an alias
Creating an alias for a key does not affect its existing aliases.
Prerequisites
Before you begin, ensure that you have:
Permissions to create an alias on the target key
If a RAM user is creating the alias, create a custom policy that grants kms:CreateAlias on both the key and the alias. For more information, see Use RAM to manage access to KMS resources.
The following policy allows user 123456 to create alias/example for key 08ec3bb9-034f-485b-b1cd-3459baa8****:
{
"Version": "1",
"Statement": [
{
"Effect": "Allow",
"Action": [
"kms:CreateAlias"
],
"Resource": [
"acs:kms:cn-hangzhou:123456:key/08ec3bb9-034f-485b-b1cd-3459baa8****",
"acs:kms:cn-hangzhou:123456:alias/example"
]
}
]
}Procedure
| Method | Steps |
|---|---|
| KMS console | 1. Log on to the KMS console. In the top navigation bar, select a region. In the left-side navigation pane, choose Resource > Keys. <br>2. On the Customer Master Keys tab or the Default Keys tab, find the key and click Details in the Actions column. <br>3. On the Alias tab, click Create Alias and enter an alias name. |
| API | Call the CreateAlias operation. |
| Alibaba Cloud CLI | Run the following command: <br>aliyun kms CreateAlias --KeyId 08ec3bb9-034f-485b-b1cd-3459baa8**** --AliasName alias/example |
Update an alias
Updating an alias reassigns it to a different key. The original key is not affected.
Prerequisites
Before you begin, ensure that you have:
Permissions on the original key, the new key, and the alias
If a RAM user is updating the alias, the custom policy must grant kms:UpdateAlias on all three resources. For more information, see Use RAM to manage access to KMS resources.
The following policy allows user 123456 to reassign alias/example from key 08ec3bb9-034f-485b-b1cd-3459baa8**` to key `127d2f84-ee5f-4f4d-9d41-dbc1aca2**:
{
"Version": "1",
"Statement": [
{
"Effect": "Allow",
"Action": [
"kms:UpdateAlias"
],
"Resource": [
"acs:kms:cn-hangzhou:123456:key/08ec3bb9-034f-485b-b1cd-3459baa8****",
"acs:kms:cn-hangzhou:123456:key/127d2f84-ee5f-4f4d-9d41-dbc1aca2****",
"acs:kms:cn-hangzhou:123456:alias/example"
]
}
]
}Procedure
| Method | Steps |
|---|---|
| API | Call the UpdateAlias operation. |
| Alibaba Cloud CLI | Run the following command: <br>aliyun kms UpdateAlias --AliasName alias/example --KeyId 127d2f84-ee5f-4f4d-9d41-dbc1aca2**** |
Query all aliases
List all aliases under your Alibaba Cloud account in a region.
Prerequisites
Before you begin, ensure that you have:
Permissions to list aliases
If a RAM user is querying aliases, the custom policy must grant kms:ListAliases on the alias resource. For more information, see Use RAM to manage access to KMS resources.
The following policy allows user 123456 to list all aliases in a region:
{
"Version": "1",
"Statement": [
{
"Effect": "Allow",
"Action": [
"kms:ListAliases"
],
"Resource": [
"acs:kms:cn-hangzhou:123456:alias"
]
}
]
}Procedure
| Method | Steps |
|---|---|
| API | Call the ListAliases operation. |
| Alibaba Cloud CLI | Run the following command: <br>aliyun kms ListAliases |
Query aliases for a specific key
List all aliases associated with a specific key.
Prerequisites
Before you begin, ensure that you have:
Permissions on the target key
If a RAM user is querying aliases for a key, the custom policy must grant kms:ListAliasesByKeyId on that key. For more information, see Use RAM to manage access to KMS resources.
The following policy allows user 123456 to query aliases for key 127d2f84-ee5f-4f4d-9d41-dbc1aca2****:
{
"Version": "1",
"Statement": [
{
"Effect": "Allow",
"Action": [
"kms:ListAliasesByKeyId"
],
"Resource": [
"acs:kms:cn-hangzhou:123456:key/127d2f84-ee5f-4f4d-9d41-dbc1aca2****"
]
}
]
}Procedure
| Method | Steps |
|---|---|
| API | Call the ListAliasesByKeyId operation. |
| Alibaba Cloud CLI | Run the following command: <br>aliyun kms ListAliasesByKeyId --KeyId 127d2f84-ee5f-4f4d-9d41-dbc1aca2**** |
Delete an alias
Deleting an alias does not delete the associated key.
Before deleting an alias, confirm it is no longer in use. If your application still references the alias, deleting it may cause data encryption to fail.
Prerequisites
Before you begin, ensure that you have:
Permissions on both the key and the alias
If a RAM user is deleting the alias, the custom policy must grant kms:DeleteAlias on both resources. For more information, see Use RAM to manage access to KMS resources.
The following policy allows user 123456 to delete alias/example from key 127d2f84-ee5f-4f4d-9d41-dbc1aca2****:
{
"Version": "1",
"Statement": [
{
"Effect": "Allow",
"Action": [
"kms:DeleteAlias"
],
"Resource": [
"acs:kms:cn-hangzhou:123456:key/127d2f84-ee5f-4f4d-9d41-dbc1aca2****",
"acs:kms:cn-hangzhou:123456:alias/example"
]
}
]
}Procedure
| Method | Steps |
|---|---|
| KMS console | 1. Log on to the KMS console. In the top navigation bar, select a region. In the left-side navigation pane, choose Resource > Keys. <br>2. On the Customer Master Keys tab or the Default Keys tab, find the key and click Details in the Actions column. <br>3. On the Alias tab, find the alias and click Delete in the Actions column. |
| API | Call the DeleteAlias operation. |
| Alibaba Cloud CLI | Run the following command: <br>aliyun kms DeleteAlias --AliasName alias/example |