# Using aliases
An *alias* is a friendly name for an AWS Payment Cryptography key. For example, an alias lets you refer to a key as `alias/test-key` instead of `arn:aws:payment-cryptography:us-east-2:111122223333:key/kwapwa6qaifllw2h`.
You can use an alias to identify a key in most key management (control plane) operations, and in [cryptographic (data plane) operations](data-operations.md).
You can also allow and deny access to AWS Payment Cryptography key based on their aliases without editing policies or managing grants. This feature is part of the service's support for [attribute-based access control](security.md) (ABAC).
Much of the power of aliases comes from your ability to change the key associated with an alias at any time. Aliases can make your code easier to write and maintain. For example, suppose you use an alias to refer to a particular AWS Payment Cryptography key and you want to change the AWS Payment Cryptography key. In that case, just associate the alias with a different key. You don't need to change your code or application configuration.
Aliases also make it easier to reuse the same code in different AWS Regions. Create aliases with the same name in multiple Regions and associate each alias with an AWS Payment Cryptography key in its Region. When the code runs in each Region, the alias refers to the associated AWS Payment Cryptography key in that Region.
You can create an alias for an AWS Payment Cryptography key by using the `CreateAlias` API.
The AWS Payment Cryptography API provides full control of aliases in each account and Region. The API includes operations to create an alias (CreateAlias), view alias names and the linked keyARN (**list-aliases**), change the AWS Payment Cryptography key associated with an alias (**update-alias**), and delete an alias (**delete-alias**).
**Topics**
+ [About aliases](alias-about.md)
+ [Using aliases in your applications](alias-using.md)
+ [Related APIs](#w2aac12c30c23)
# About aliases
Learn how aliases work in AWS Payment Cryptography.
**An alias is an independent AWS resource**
An alias is not a property of an AWS Payment Cryptography key. The actions that you take on the alias don't affect its associated key. You can create an alias for an AWS Payment Cryptography key and then update the alias so it's associated with a different AWS Payment Cryptography key. You can even delete the alias without any effect on the associated AWS Payment Cryptography key. If you delete a AWS Payment Cryptography key, all aliases associated with that key will become unassigned.
If you specify an alias as the resource in an IAM policy, the policy refers to the alias, not to the associated AWS Payment Cryptography key.
**Each alias has a friendly name**
When you create an alias, you specify the alias name prefixed by `alias/`. For instance `alias/test_1234`
**Each alias is associated with one AWS Payment Cryptography key at a time**
The alias and its AWS Payment Cryptography key must be in the same account and Region.
An AWS Payment Cryptography key can be associated with more than one alias concurrently, but each alias can only be mapped to a single key
For example, this `list-aliases` output shows that the `alias/sampleAlias1` alias is associated with exactly one target AWS Payment Cryptography key, which is represented by the `KeyArn` property.
```
$ aws payment-cryptography list-aliases
```
```
{
"Aliases": [
{
"AliasName": "alias/sampleAlias1",
"KeyArn": "arn:aws:payment-cryptography:us-east-2:111122223333:key/kwapwa6qaifllw2h"
}
]
}
```
**Multiple aliases can be associated with the same AWS Payment Cryptography key**
For example, you can associate the `alias/sampleAlias1;` and `alias/sampleAlias2` aliases with the same key.
```
$ aws payment-cryptography list-aliases
```
```
{
"Aliases": [
{
"AliasName": "alias/sampleAlias1",
"KeyArn": "arn:aws:payment-cryptography:us-east-2:111122223333:key/kwapwa6qaifllw2h"
},
{
"AliasName": "alias/sampleAlias2",
"KeyArn": "arn:aws:payment-cryptography:us-east-2:111122223333:key/kwapwa6qaifllw2h"
}
]
}
```
**An alias must be unique for a given account and Region**
For example, you can have only one `alias/sampleAlias1` alias in each account and Region. Aliases are case-sensitive, but we recommend against using aliases that only differ in capitalization as they can be prone to error. You cannot change an alias name. However, you can delete the alias and create a new alias with the desired name.
**You can create an alias with the same name in different Regions**
For example, you can have alias `alias/sampleAlias2` in US East (N. Virginia) and alias `alias/sampleAlias2` in US West (Oregon). Each alias would be associated with an AWS Payment Cryptography key in its Region. If your code refers to an alias name like `alias/finance-key`, you can run it in multiple Regions. In each Region, it uses a different alias/sampleAlias2. For details, see [Using aliases in your applications](alias-using.md).
**You can change the AWS Payment Cryptography key associated with an alias**
You can use the `UpdateAlias` operation to associate an alias with a different AWS Payment Cryptography key. For example, if the `alias/sampleAlias2` alias is associated with the `arn:aws:payment-cryptography:us-east-2:111122223333:key/kwapwa6qaifllw2h ` AWS Payment Cryptography key, you can update it so it is associated with the `arn:aws:payment-cryptography:us-east-2:111122223333:key/tqv5yij6wtxx64pi` key.
AWS Payment Cryptography doesn't validate that the old and new keys have all the same attributes such as key usage. Updating with a different key type may result in problems in your application.
**Some keys don't have aliases**
An alias is an optional feature and not all keys will have aliases unless you choose to operate your environment in this way. Keys can be associated with Aliases using the `create-alias` command. Also, you can use the update-alias operation to change the AWS Payment Cryptography key associated with an alias and the delete-alias operation to delete an alias. As a result, some AWS Payment Cryptography keys might have several aliases, and some might have none.
**Mapping a key to an alias**
You can map a key (represented by an ARN) to one or more aliases using the `create-alias` command. This command is not idempotent - to update an alias, use the update-alias command.
```
$ aws payment-cryptography create-alias --alias-name alias/sampleAlias1 \
--key-arn arn:aws:payment-cryptography:us-east-2:111122223333:key/kwapwa6qaifllw2h
```
```
{
"Alias": {
"AliasName": "alias/alias/sampleAlias1",
"KeyArn": "arn:aws:payment-cryptography:us-east-2:111122223333:key/kwapwa6qaifllw2h"
}
}
```
# Using aliases in your applications
You can use an alias to represent an AWS Payment Cryptography key in your application code. The `key-identifier` parameter in AWS Payment Cryptography [data operations](data-operations.md) as well as other operations like List Keys accepts an alias name or alias ARN.
```
$ aws payment-cryptography-data generate-card-validation-data --key-identifier alias/BIN_123456_CVK --primary-account-number=171234567890123 --generation-attributes CardVerificationValue2={CardExpiryDate=0123}
```
When using an alias ARN, remember that the alias mapping to an AWS Payment Cryptography key is defined in the account that owns the AWS Payment Cryptography key and might differ in each Region.
One of the most powerful uses of aliases is in applications that run in multiple AWS Regions.
You could create a different version of your application in each Region or use a dictionary, configuration or switch statement to select the right AWS Payment Cryptography key for each Region. But it might be easier to create an alias with the same alias name in each Region. Remember that the alias name is case-sensitive.
## Related APIs
**[Tags](tagging-keys.md)**
Tags are key and value pairs that act as metadata for organizing your AWS Payment Cryptography keys. They can be used to flexibly identify keys or group one or more keys together.