# Amazon Verified Permissions policy store aliases
Policy store aliases

A policy store alias is a friendly name for a policy store. For example, policy store aliases let you refer to a policy store using `policy-store-alias/example-policy-store` instead of `PSEXAMPLEabcdefg111111`. Policy store aliases can be used in any Verified Permissions operation that accepts a `policyStoreId` input parameter.

You can create a policy store alias for a policy store by using the `CreatePolicyStoreAlias` API or by using the `AWS::VerifiedPermissions::PolicyStoreAlias` CloudFormation resource.

The Amazon Verified Permissions API provides full control of policy store aliases in each Amazon Web Services account and Region. The API includes operations to create a policy store alias (`CreatePolicyStoreAlias`), view policy store alias names and policy store alias ARNs (`GetPolicyStoreAlias`, `ListPolicyStoreAliases`), and delete a policy store alias (`DeletePolicyStoreAlias`).

**Topics**
+ [

## Properties of policy store aliases
](#alias-properties)
+ [

# Creating Amazon Verified Permissions policy store aliases
](policy-store-aliases-create.md)
+ [

# Retrieving Amazon Verified Permissions policy store aliases
](policy-store-aliases-retrieve.md)
+ [

# Deleting Amazon Verified Permissions policy store aliases
](policy-store-aliases-delete.md)
+ [

# Using Amazon Verified Permissions policy store aliases in API operations
](policy-store-aliases-using.md)
+ [

# Controlling access to policy store aliases
](policy-store-aliases-control-access.md)

## Properties of policy store aliases


How policy store aliases work in Amazon Verified Permissions.

**A policy store alias is an independent Amazon resource**  
A policy store alias is not a property of a policy store. The actions that you take on the policy store alias don't affect its associated policy store. You can delete the policy store alias without any effect on the associated policy store. If you delete a policy store, all policy store aliases associated with that policy store are also deleted.

Each policy store alias has an Amazon Resource Name (ARN) that uniquely identifies the policy store alias. If you specify a policy store alias as the resource in an IAM policy, the policy refers to the policy store alias, not to the associated policy store.

**Each policy store alias has two formats**  
When you create a policy store alias, you specify the policy store alias name. Amazon Verified Permissions creates the policy store alias ARN for you.
+ A policy store alias ARN is an Amazon Resource Name (ARN) that uniquely identifies the policy store alias.

  ```
  # Alias ARN
  arn:aws:verifiedpermissions:us-east-1:123456789012:policy-store-alias/example-policy-store
  ```
+ A policy store alias name that is unique in the Amazon Web Services account and Region. In the Amazon Verified Permissions API, the policy store alias name is always prefixed by `policy-store-alias/`.

  ```
  # Alias name
  policy-store-alias/example-policy-store
  ```

**Policy store aliases are not secret**  
Policy store aliases may be displayed in plaintext in CloudTrail logs and other output. Do not include confidential or sensitive information in the policy store alias name.

**Each policy store alias is associated with one policy store at a time**  
The policy store alias and its associated policy store must belong to the same Amazon Web Services account and Region. You can associate a policy store alias with any policy store in the same Amazon Web Services account and Region.

For example, this `ListPolicyStoreAliases` output shows that the `example-policy-store` policy store alias is associated with exactly one target policy store, which is represented by the `policyStoreId` property.

```
{
    "aliasName": "policy-store-alias/example-policy-store",
    "policyStoreId": "PSEXAMPLEabcdefg111111",
    "aliasArn": "arn:aws-cn:verifiedpermissions:us-west-2:123456789012:policy-store-alias/example-policy-store",
    "createdAt": "2024-01-15T12:30:00.000000+00:00",
    "state": "Active"
}
```

**Multiple aliases can be associated with the same policy store**  
For example, you can associate the `example-policy-store` and `example-policy-store-2` aliases with the same policy store.

```
[
    {
        "aliasName": "policy-store-alias/example-policy-store",
        "policyStoreId": "PSEXAMPLEabcdefg111111",
        "aliasArn": "arn:aws-cn:verifiedpermissions:us-west-2:123456789012:policy-store-alias/example-policy-store",
        "createdAt": "2024-01-15T12:30:00.000000+00:00",
        "state": "Active"
    },
    {
        "aliasName": "policy-store-alias/example-policy-store-2",
        "policyStoreId": "PSEXAMPLEabcdefg111111",
        "aliasArn": "arn:aws-cn:verifiedpermissions:us-west-2:123456789012:policy-store-alias/example-policy-store-2",
        "createdAt": "2024-01-16T09:15:00.000000+00:00",
        "state": "Active"
    }
]
```

**A policy store alias must be unique in an Amazon Web Services account and Region**  
For example, you can have only one policy store alias with the name `example-policy-store` in each Amazon Web Services account and Region. Policy store aliases are case-sensitive. You cannot change a policy store alias name. However, you can delete the policy store alias and create a new policy store alias with the desired name after the 24-hour reservation period expires.

You can create policy store aliases with the same name in different Regions. Each policy store alias will have a unique ARN. If your code refers to a policy store alias name like `policy-store-alias/example-policy-store`, you can run it in multiple Regions. In each Region, it uses a different policy store.

**Policy store aliases are soft deleted**  
When a policy store alias is deleted, the policy store alias name is reserved for a period of 24 hours. If you attempt to create a policy store alias with the same name during this period, the request will be rejected. During this period, `GetPolicyStoreAlias` returns the policy store alias with the `PendingDeletion` state.

**You can use aliases to identify policy stores**  
You can use a policy store alias to identify a policy store in all operations that accept a `policyStoreId` (for example, `IsAuthorized`). In such cases, the policy store alias name must be prefixed with `policy-store-alias/`. Policy store aliases cannot be used to identify a policy store for the `DeletePolicyStore` operation.

You cannot use a policy store alias name or policy store alias ARN to identify a policy store in the `Resource` element of an IAM policy. To control access to a policy store when it is referenced through a policy store alias, see [Controlling access to policy store aliases](policy-store-aliases-control-access.md).

# Creating Amazon Verified Permissions policy store aliases
Creating policy store aliases

You can create a policy store alias to reference a policy store using a friendly name. The name of a policy store alias must be unique per Amazon Web Services account and Region. Policy store aliases may only be associated with policy stores that are owned by the same Amazon Web Services account and active in the same Region as the policy store alias. Policy store aliases are separate resources with their own ARNs and IAM authorization.

By default, only 10 policy store aliases can be associated with the same policy store.

**Note**  
`CreatePolicyStoreAlias` is idempotent. If you call the `CreatePolicyStoreAlias` operation with a policy store alias name and policy store ID that match an existing policy store alias, the `CreatePolicyStoreAlias` operation succeeds and returns the existing policy store alias. However, if you call the `CreatePolicyStoreAlias` operation with an existing policy store alias name but a different policy store ID, the operation returns a `ConflictException`.

------
#### [ Amazon CLI ]

**To create a policy store alias**  
You can create a policy store alias by using the [CreatePolicyStoreAlias](https://docs.amazonaws.cn/verifiedpermissions/latest/apireference/API_CreatePolicyStoreAlias.html) operation. The following example creates a policy store alias with the name `example-policy-store`.

```
$ aws verifiedpermissions create-policy-store-alias \
    --alias-name policy-store-alias/example-policy-store \
    --policy-store-id PSEXAMPLEabcdefg111111
{
    "aliasName": "policy-store-alias/example-policy-store",
    "policyStoreId": "PSEXAMPLEabcdefg111111",
    "aliasArn": "arn:aws-cn:verifiedpermissions:us-west-2:123456789012:policy-store-alias/example-policy-store",
    "createdAt": "2024-01-15T12:30:00.000000+00:00"
}
```

------

# Retrieving Amazon Verified Permissions policy store aliases
Retrieving policy store aliases

You can retrieve information about policy store aliases using the `GetPolicyStoreAlias` operation to get details about a specific policy store alias, or the `ListPolicyStoreAliases` operation to list all policy store aliases in your Amazon Web Services account and Region.

## Getting a policy store alias


Use the `GetPolicyStoreAlias` operation to retrieve details about a specific policy store alias, including the associated policy store ID.

------
#### [ Amazon CLI ]

**To retrieve details about a policy store alias**  
You can retrieve a policy store alias by using the [GetPolicyStoreAlias](https://docs.amazonaws.cn/verifiedpermissions/latest/apireference/API_GetPolicyStoreAlias.html) operation. The following example retrieves details for a policy store alias with the name `example-policy-store`.

```
$ aws verifiedpermissions get-policy-store-alias \
    --alias-name policy-store-alias/example-policy-store
{
    "aliasName": "policy-store-alias/example-policy-store",
    "policyStoreId": "PSEXAMPLEabcdefg111111",
    "aliasArn": "arn:aws-cn:verifiedpermissions:us-west-2:123456789012:policy-store-alias/example-policy-store",
    "createdAt": "2024-01-15T12:30:00.000000+00:00",
    "state": "Active"
}
```

------

## Listing policy store aliases


Use the `ListPolicyStoreAliases` operation to list all policy store aliases in your Amazon Web Services account and Region. You can use the `filter` parameter to list only policy store aliases associated with a specific policy store.

------
#### [ Amazon CLI ]

**To list all policy store aliases**  
You can list policy store aliases by using the [ListPolicyStoreAliases](https://docs.amazonaws.cn/verifiedpermissions/latest/apireference/API_ListPolicyStoreAliases.html) operation. The following example lists all policy store aliases owned by the 123456789012 Amazon Web Services account in the us-west-2 Region.

```
$ aws verifiedpermissions list-policy-store-aliases
{
    "policyStoreAliases": [
        {
            "aliasName": "policy-store-alias/example-policy-store",
            "policyStoreId": "PSEXAMPLEabcdefg111111",
            "aliasArn": "arn:aws-cn:verifiedpermissions:us-west-2:123456789012:policy-store-alias/example-policy-store",
            "createdAt": "2024-01-15T12:30:00.000000+00:00",
            "state": "Active"
        },
        {
            "aliasName": "policy-store-alias/example-policy-store-2",
            "policyStoreId": "PSEXAMPLEabcdefg111111",
            "aliasArn": "arn:aws-cn:verifiedpermissions:us-west-2:123456789012:policy-store-alias/example-policy-store-2",
            "createdAt": "2024-01-16T09:15:00.000000+00:00",
            "state": "Active"
        },
        {
            "aliasName": "policy-store-alias/example-policy-store-3",
            "policyStoreId": "PSEXAMPLEabcdefg222222",
            "aliasArn": "arn:aws-cn:verifiedpermissions:us-west-2:123456789012:policy-store-alias/example-policy-store-3",
            "createdAt": "2024-01-17T14:45:00.000000+00:00",
            "state": "Active"
        }
    ]
}
```

**To list policy store aliases for a specific policy store**  
Use the `filter` parameter to list only aliases associated with a specific policy store.

```
$ aws verifiedpermissions list-policy-store-aliases \
    --filter '{"policyStoreId": "PSEXAMPLEabcdefg111111"}'
{
    "policyStoreAliases": [
        {
            "aliasName": "policy-store-alias/example-policy-store",
            "policyStoreId": "PSEXAMPLEabcdefg111111",
            "aliasArn": "arn:aws-cn:verifiedpermissions:us-west-2:123456789012:policy-store-alias/example-policy-store",
            "createdAt": "2024-01-15T12:30:00.000000+00:00",
            "state": "Active"
        },
        {
            "aliasName": "policy-store-alias/example-policy-store-2",
            "policyStoreId": "PSEXAMPLEabcdefg111111",
            "aliasArn": "arn:aws-cn:verifiedpermissions:us-west-2:123456789012:policy-store-alias/example-policy-store-2",
            "createdAt": "2024-01-16T09:15:00.000000+00:00",
            "state": "Active"
        }
    ]
}
```

------

# Deleting Amazon Verified Permissions policy store aliases
Deleting policy store aliases

You can delete a policy store alias when it is no longer needed. Deleting a policy store alias does not affect the associated policy store. Deleting a policy store deletes all policy store aliases associated with that policy store.

After you delete a policy store alias, the policy store alias name is reserved for 24 hours and cannot be reused during this period.

------
#### [ Amazon CLI ]

**To delete a policy store alias**  
You can delete a policy store alias by using the [DeletePolicyStoreAlias](https://docs.amazonaws.cn/verifiedpermissions/latest/apireference/API_DeletePolicyStoreAlias.html) operation. The following example deletes a policy store alias with the name `example-policy-store`.

```
$ aws verifiedpermissions delete-policy-store-alias \
    --alias-name policy-store-alias/example-policy-store
```

------

# Using Amazon Verified Permissions policy store aliases in API operations
Using policy store aliases

Any Amazon Verified Permissions operation that accepts a `policyStoreId` parameter, such as [IsAuthorized](https://docs.amazonaws.cn/verifiedpermissions/latest/apireference/API_IsAuthorized.html), [IsAuthorizedWithToken](https://docs.amazonaws.cn/verifiedpermissions/latest/apireference/API_IsAuthorizedWithToken.html), and [GetPolicyStore](https://docs.amazonaws.cn/verifiedpermissions/latest/apireference/API_GetPolicyStore.html), can accept a policy store alias name in place of the policy store ID.

**Important**  
When you use a policy store alias as the value of a `policyStoreId` parameter, you must include the `policy-store-alias/` prefix. For example, use `policy-store-alias/example-policy-store`, not `example-policy-store`.

## Using Policy store aliases in Operations


The following `IsAuthorized` command uses a policy store alias with the name `example-policy-store` to identify a policy store.

------
#### [ Amazon CLI ]

```
$ aws verifiedpermissions is-authorized \
    --policy-store-id policy-store-alias/example-policy-store \
    --principal entityType=User,entityId=alice \
    --action actionType=Action,actionId=view \
    --resource entityType=Photo,entityId=photo123
```

------

**Note**  
You cannot use a policy store alias in place of the `policyStoreId` field for the [DeletePolicyStore](https://docs.amazonaws.cn/verifiedpermissions/latest/apireference/API_DeletePolicyStore.html) operation.

## Using Policy store aliases Across Amazon Web Services Regions


One of the most powerful uses of aliases is in applications that run in multiple Amazon Web Services Regions. For example, you might have a global application that uses different policy stores in each Region.
+ In us-east-1, you want to use `PSEXAMPLEabcdefg111111`.
+ In eu-west-1, you want to use `PSEXAMPLEabcdefg222222`.

You could create a different version of your application in each Region or use a dictionary or switch statement to select the right policy store for each Region. But it's much easier to create a policy store alias with the same policy store alias name in each Region. Remember that the policy store alias name is case-sensitive.

------
#### [ Amazon CLI ]

```
$ aws --region us-east-1 verifiedpermissions create-policy-store-alias \
    --alias-name policy-store-alias/my-app \
    --policy-store-id PSEXAMPLEabcdefg111111

$ aws --region eu-west-1 verifiedpermissions create-policy-store-alias \
    --alias-name policy-store-alias/my-app \
    --policy-store-id PSEXAMPLEabcdefg222222
```

------

Then, use the policy store alias in your code. When your code runs in each Region, the policy store alias will refer to its associated policy store in that Region.

------
#### [ Amazon CLI ]

```
$ aws verifiedpermissions is-authorized \
    --policy-store-id policy-store-alias/my-app \
    --principal entityType=User,entityId=alice \
    --action actionType=Action,actionId=view \
    --resource entityType=Photo,entityId=photo123
```

------

However, there is a risk that the policy store alias might be deleted. In that case, the application's attempts to use the policy store alias name will fail, and you might need to recreate or update the policy store alias. To mitigate this risk, be cautious about giving principals permission to manage the policy store aliases that you use in your application.

# Controlling access to policy store aliases
Controlling access

Principals who manage policy store aliases must have permission to interact with those policy store aliases and, for some operations, the policy store that the policy store alias is associated with. You can provide these permissions using IAM policies.

The following sections describe the permissions required to create and manage policy store aliases.

## verifiedpermissions:CreatePolicyStoreAlias


To create a policy store alias, the principal needs the following permissions for both the policy store alias and for the associated policy store.
+ `verifiedpermissions:CreatePolicyStoreAlias` for the policy store alias. Provide this permission in an IAM policy that is attached to the principal who is allowed to create the policy store alias.

  The following example policy statement specifies a particular policy store alias in a `Resource` element. But you can list multiple policy store alias ARNs or specify a policy store alias pattern, such as `"sample*"`. You can also specify a `Resource` value of `"*"` to allow the principal to create any policy store alias in the Amazon Web Services account and Region.

  ```
  {
    "Sid": "IAMPolicyForCreateAlias",
    "Effect": "Allow",
    "Action": "verifiedpermissions:CreatePolicyStoreAlias",
    "Resource": "arn:aws:verifiedpermissions:us-east-1:123456789012:policy-store-alias/example-policy-store"
  }
  ```
+ `verifiedpermissions:CreatePolicyStoreAlias` for the associated policy store. This permission must be provided in an IAM policy.

  ```
  {
    "Sid": "PolicyStorePermissionForAlias",
    "Effect": "Allow",
    "Action": "verifiedpermissions:CreatePolicyStoreAlias",
    "Resource": "arn:aws:verifiedpermissions::123456789012:policy-store/PSEXAMPLEabcdefg111111"
  }
  ```

## verifiedpermissions:GetPolicyStoreAlias


To get details about a specific policy store alias, the principal must have `verifiedpermissions:GetPolicyStoreAlias` permission for the policy store alias in an IAM policy.

The following example policy statement gives the principal permission to get a specific policy store alias.

```
{
  "Sid": "IAMPolicyForGetAlias",
  "Effect": "Allow",
  "Action": "verifiedpermissions:GetPolicyStoreAlias",
  "Resource": "arn:aws:verifiedpermissions:us-east-1:123456789012:policy-store-alias/example-policy-store"
}
```

## verifiedpermissions:ListPolicyStoreAliases


To list policy store aliases in the Amazon Web Services account and Region, the principal must have `verifiedpermissions:ListPolicyStoreAliases` permission in an IAM policy. Because this policy is not related to any particular policy store or policy store alias resource, the value of the resource element in the policy must be `"*"`.

For example, the following IAM policy statement gives the principal permission to list all policy store aliases in the Amazon Web Services account.

```
{
  "Sid": "IAMPolicyForListingAliases",
  "Effect": "Allow",
  "Action": "verifiedpermissions:ListPolicyStoreAliases",
  "Resource": "*"
}
```

## verifiedpermissions:DeletePolicyStoreAlias


To delete a policy store alias, the principal needs permission for just the policy store alias.

**Note**  
Deleting a policy store alias has no effect on the associated policy store, although applications that reference the policy store alias will receive errors. If you mistakenly delete a policy store alias, you can recreate it after the 24-hour reservation period.

The principal needs `verifiedpermissions:DeletePolicyStoreAlias` permission for the policy store alias. Provide this permission in an IAM policy attached to the principal who is allowed to delete the policy store alias.

The following example policy statement specifies the policy store alias in a `Resource` element. But you can list multiple policy store alias ARNs or specify a policy store alias pattern, such as `"sample*"`. You can also specify a `Resource` value of `"*"` to allow the principal to delete any policy store alias in the Amazon Web Services account and Region.

```
{
  "Sid": "IAMPolicyForDeleteAlias",
  "Effect": "Allow",
  "Action": "verifiedpermissions:DeletePolicyStoreAlias",
  "Resource": "arn:aws:verifiedpermissions:us-east-1:123456789012:policy-store-alias/example-policy-store"
}
```

## Limiting Policy store alias Permissions


You can use a policy store alias to reference a policy store in any operation that accepts a `policyStoreId` field as input. When you do, Amazon Verified Permissions authorizes `verifiedpermissions:GetPolicyStoreAlias` against the policy store alias and the requested operation against the associated policy store.

For example, if the `IsAuthorized` operation is performed using a policy store alias, the principal needs both:
+ `verifiedpermissions:GetPolicyStoreAlias` permission for the policy store alias
+ `verifiedpermissions:IsAuthorized` permission for the associated policy store

The following example policy grants permission to call `IsAuthorized` using a specific policy store alias.

```
{
  "Sid": "IAMPolicyForAliasUsage",
  "Effect": "Allow",
  "Action": "verifiedpermissions:GetPolicyStoreAlias",
  "Resource": "arn:aws:verifiedpermissions:us-east-1:123456789012:policy-store-alias/example-policy-store"
},
{
  "Sid": "IAMPolicyForPolicyStoreOperation",
  "Effect": "Allow",
  "Action": "verifiedpermissions:IsAuthorized",
  "Resource": "arn:aws:verifiedpermissions::123456789012:policy-store/PSEXAMPLEabcdefg111111"
}
```

To limit which policy store aliases a principal can use, restrict the `verifiedpermissions:GetPolicyStoreAlias` permission. For example, the following policy allows the principal to use any policy store alias except those beginning with `Restricted`.

```
{
  "Sid": "IAMPolicyForAliasAllow",
  "Effect": "Allow",
  "Action": "verifiedpermissions:GetPolicyStoreAlias",
  "Resource": "arn:aws:verifiedpermissions:us-east-1:123456789012:policy-store-alias/*"
},
{
  "Sid": "IAMPolicyForAliasDeny",
  "Effect": "Deny",
  "Action": "verifiedpermissions:GetPolicyStoreAlias",
  "Resource": "arn:aws:verifiedpermissions:us-east-1:123456789012:policy-store-alias/Restricted*"
}
```