# Working with S3 Access Grants instances To get started with using AmazonS3 Access Grants, you first create an S3 Access Grants instance. You can create only one S3 Access Grants instance per AWS Region per account. The S3 Access Grants instance serves as the container for your S3 Access Grants resources, which include registered locations and grants. With S3 Access Grants, you can create permission grants to your S3 data for AWS Identity and Access Management (IAM) users and roles. If you've [added your corporate identity directory](https://docs.aws.amazon.com/singlesignon/latest/userguide/manage-your-identity-source-idp.html) to AWS IAM Identity Center, you can associate this IAM Identity Center instance of your corporate directory with your S3 Access Grants instance. After you've done so, you can create access grants for your corporate users and groups. If you haven't yet added your corporate directory to IAM Identity Center, you can associate your S3 Access Grants instance with an IAM Identity Center instance later. **Topics** + [ # Create an S3 Access Grants instance ](access-grants-instance-create.md) + [ # Get the details of an S3 Access Grants instance ](access-grants-instance-view.md) + [ # List your S3 Access Grants instances ](access-grants-instance-list.md) + [ # Associate or disassociate your IAM Identity Center instance ](access-grants-instance-idc.md) + [ # Delete an S3 Access Grants instance ](access-grants-instance-delete.md) # Create an S3 Access Grants instance To get started with using AmazonS3 Access Grants, you first create an S3 Access Grants instance. You can create only one S3 Access Grants instance per AWS Region per account. The S3 Access Grants instance serves as the container for your S3 Access Grants resources, which include registered locations and grants. With S3 Access Grants, you can create permission grants to your S3 data for AWS Identity and Access Management (IAM) users and roles. If you've [added your corporate identity directory](https://docs.aws.amazon.com/singlesignon/latest/userguide/manage-your-identity-source-idp.html) to AWS IAM Identity Center, you can associate this IAM Identity Center instance of your corporate directory with your S3 Access Grants instance. After you've done so, you can create access grants for your corporate users and groups. If you haven't yet added your corporate directory to IAM Identity Center, you can associate your S3 Access Grants instance with an IAM Identity Center instance later. You can create an S3 Access Grants instance by using the Amazon S3 console, the AWS Command Line Interface (AWS CLI), the Amazon S3 REST API, and AWS SDKs. ## Using the S3 console Before you can grant access to your S3 data with S3 Access Grants, you must first create an S3 Access Grants instance in the same AWS Region as your S3 data. **Prerequisites** If you want to grant access to your S3 data by using identities from your corporate directory, [add your corporate identity directory](https://docs.aws.amazon.com/singlesignon/latest/userguide/manage-your-identity-source-idp.html) to AWS IAM Identity Center. If you're not yet ready to do so, you can associate your S3 Access Grants instance with an IAM Identity Center instance later. **To create an S3 Access Grants instance** 1. Sign in to the AWS Management Console and open the Amazon S3 console at [https://console.aws.amazon.com/s3/](https://console.aws.amazon.com/s3/). 1. In the navigation bar, choose the name of the currently displayed AWS Region. Next, choose the Region that you want to switch to. 1. In the left navigation pane, choose **Access Grants**. 1. On the **S3 Access Grants** page, choose **Create S3 Access Grants instance**. 1. In **Step 1** of the **Set up Access Grants instance** wizard, verify that you want to create the instance in the current AWS Region. Make sure that this is the same AWS Region where your S3 data is located. You can create one S3 Access Grants instance per AWS Region per account. 1. (Optional) If you've [added your corporate identity directory](https://docs.aws.amazon.com/singlesignon/latest/userguide/manage-your-identity-source-idp.html) to AWS IAM Identity Center, you can associate this IAM Identity Center instance of your corporate directory with your S3 Access Grants instance. To do so, select **Add IAM Identity Center instance in *region***. Then enter the IAM Identity Center instance Amazon Resource Name (ARN). If you haven't yet added your corporate directory to IAM Identity Center, you can associate your S3 Access Grants instance with an IAM Identity Center instance later. 1. To create the S3 Access Grants instance, choose **Next**. To register a location, see [Step 2 - register a location](https://docs.aws.amazon.com/AmazonS3/latest/userguide/access-grants-instance.html). 1. If **Next** or **Create S3 Access Grants instance** is disabled: **Cannot create instance** + You might already have an S3 Access Grants instance in the same AWS Region. In the left navigation pane, choose **Access Grants**. On the **S3 Access Grants** page, scroll down to the **S3 Access Grants instance in your account** section o determine if an instance already exists. + You might not have the `s3:CreateAccessGrantsInstance` permission which is required to create an S3 Access Grants instance. Contact your account administrator. For additional permissions that are required if you are associating an IAM Identity Center instance, with your S3 Access Grants instance, see [https://docs.aws.amazon.com/AmazonS3/latest/API/API_control_CreateAccessGrantsInstance.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_control_CreateAccessGrantsInstance.html) . ## Using the AWS CLI To install the AWS CLI, see [Installing the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) in the *AWS Command Line Interface User Guide*. To use the following example command, replace the `user input placeholders` with your own information. **Example Create an S3 Access Grants instance** ``` aws s3control create-access-grants-instance \ --account-id 111122223333 \ --region us-east-2 ``` Response: ``` { "CreatedAt": "2023-05-31T17:54:07.893000+00:00", "AccessGrantsInstanceId": "default", "AccessGrantsInstanceArn": "arn:aws:s3:us-east-2:111122223333:access-grants/default" } ``` ## Using the REST API You can use the Amazon S3 REST API to create an S3 Access Grants instance. For information on the REST API support for managing an S3 Access Grants instance, see the following sections in the *Amazon Simple Storage Service API Reference*: + [https://docs.aws.amazon.com/AmazonS3/latest/API/API_control_AssociateAccessGrantsIdentityCenter.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_control_AssociateAccessGrantsIdentityCenter.html) + [https://docs.aws.amazon.com/AmazonS3/latest/API/API_control_CreateAccessGrantsInstance.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_control_CreateAccessGrantsInstance.html) + [https://docs.aws.amazon.com/AmazonS3/latest/API/API_control_DeleteAccessGrantsInstance.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_control_DeleteAccessGrantsInstance.html) + [https://docs.aws.amazon.com/AmazonS3/latest/API/API_control_DissociateAccessGrantsIdentityCenter.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_control_DissociateAccessGrantsIdentityCenter.html) + [https://docs.aws.amazon.com/AmazonS3/latest/API/API_control_GetAccessGrantsInstance.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_control_GetAccessGrantsInstance.html) + [https://docs.aws.amazon.com/AmazonS3/latest/API/API_control_GetAccessGrantsInstanceForPrefix.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_control_GetAccessGrantsInstanceForPrefix.html) + [https://docs.aws.amazon.com/AmazonS3/latest/API/API_control_GetAccessGrantsInstanceResourcePolicy.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_control_GetAccessGrantsInstanceResourcePolicy.html) + [https://docs.aws.amazon.com/AmazonS3/latest/API/API_control_ListAccessGrantsInstances.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_control_ListAccessGrantsInstances.html) + [https://docs.aws.amazon.com/AmazonS3/latest/API/API_control_PutAccessGrantsInstanceResourcePolicy.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_control_PutAccessGrantsInstanceResourcePolicy.html) ## Using the AWS SDKs This section provides an example of how to create an S3 Access Grants instance by using the AWS SDKs. ------ #### [ Java ] This example creates the S3 Access Grants instance, which serves as a container for your individual access grants. You can have one S3 Access Grants instance per AWS Region in your account. The response includes the instance ID `default` and an Amazon Resource Name (ARN) that's generated for your S3 Access Grants instance. **Example Create an S3 Access Grants instance request** ``` public void createAccessGrantsInstance() { CreateAccessGrantsInstanceRequest createRequest = CreateAccessGrantsInstanceRequest.builder().accountId("111122223333").build(); CreateAccessGrantsInstanceResponse createResponse = s3Control.createAccessGrantsInstance(createRequest);LOGGER.info("CreateAccessGrantsInstanceResponse: " + createResponse); } ``` Response: ``` CreateAccessGrantsInstanceResponse( CreatedAt=2023-06-07T01:46:20.507Z, AccessGrantsInstanceId=default, AccessGrantsInstanceArn=arn:aws:s3:us-east-2:111122223333:access-grants/default) ``` ------ # Get the details of an S3 Access Grants instance You can get the details of your Amazon S3 Access Grants instance in a particular AWS Region. You can get the details of your S3 Access Grants instance by using the Amazon S3 console, the AWS Command Line Interface (AWS CLI), the Amazon S3 REST API, and the AWS SDKs. ## Using the S3 console **To get the details of an S3 Access Grants instance** 1. Sign in to the AWS Management Console and open the Amazon S3 console at [https://console.aws.amazon.com/s3/](https://console.aws.amazon.com/s3/). 1. In the left navigation pane, choose **Access Grants**. 1. On the **S3 Access Grants** page, choose the Region that contains the S3 Access Grants instance that you want to work with. 1. The **S3 Access Grants** page lists your S3 Access Grants instances and any cross-account instances that have been shared with your account. To view the details of an instance, choose **View details**. ## Using the AWS CLI To install the AWS CLI, see [Installing the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) in the *AWS Command Line Interface User Guide*. To use the following example command, replace the `user input placeholders` with your own information. **Example – Get the details of an S3 Access Grants instance** ``` aws s3control get-access-grants-instance \ --account-id 111122223333 \ --region us-east-2 ``` Response: ``` { "AccessGrantsInstanceArn": "arn:aws:s3:us-east-2: 111122223333:access-grants/default", "AccessGrantsInstanceId": "default", "CreatedAt": "2023-05-31T17:54:07.893000+00:00" } ``` ## Using the REST API For information about the Amazon S3 REST API support for managing an S3 Access Grants instance, see the following sections in the *Amazon Simple Storage Service API Reference*: + [https://docs.aws.amazon.com/AmazonS3/latest/API/API_control_GetAccessGrantsInstance.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_control_GetAccessGrantsInstance.html) + [https://docs.aws.amazon.com/AmazonS3/latest/API/API_control_GetAccessGrantsInstanceForPrefix.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_control_GetAccessGrantsInstanceForPrefix.html) ## Using the AWS SDKs This section provides examples of how to get the details of an S3 Access Grants instance by using the AWS SDKs. To use the following examples, replace the `user input placeholders` with your own information. ------ #### [ Java ] **Example – Get an S3 Access Grants instance** ``` public void getAccessGrantsInstance() { GetAccessGrantsInstanceRequest getRequest = GetAccessGrantsInstanceRequest.builder() .accountId("111122223333") .build(); GetAccessGrantsInstanceResponse getResponse = s3Control.getAccessGrantsInstance(getRequest); LOGGER.info("GetAccessGrantsInstanceResponse: " + getResponse); } ``` Response: ``` GetAccessGrantsInstanceResponse( AccessGrantsInstanceArn=arn:aws:s3:us-east-2: 111122223333:access-grants/default, CreatedAt=2023-06-07T01:46:20.507Z) ``` ------ # List your S3 Access Grants instances You can list your S3 Access Grants instances, including the instances that have been shared with you through AWS Resource Access Manager (AWS RAM). You can list your S3 Access Grants instances by using the Amazon S3 console, the AWS Command Line Interface (AWS CLI), the Amazon S3 REST API, and the AWS SDKs. ## Using the S3 console **To list your S3 Access Grants instances** 1. Sign in to the AWS Management Console and open the Amazon S3 console at [https://console.aws.amazon.com/s3/](https://console.aws.amazon.com/s3/). 1. In the left navigation pane, choose **Access Grants**. 1. On the **S3 Access Grants** page, choose the Region that contains the S3 Access Grants instance that you want to work with. 1. The **S3 Access Grants** page lists your S3 Access Grants instances and any cross-account instances that have been shared with your account. To view the details of an instance, choose **View details**. ## Using the AWS CLI To install the AWS CLI, see [Installing the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) in the *AWS Command Line Interface User Guide*. To use the following example command, replace the `user input placeholders` with your own information. **Example – List all S3 Access Grants instances for an account** This action lists the S3 Access Grants instances for an account. You can only have one S3 Access Grants instance per AWS Region. This action also lists other cross-account S3 Access Grants instances that your account has access to. ``` aws s3control list-access-grants-instances \ --account-id 111122223333 \ --region us-east-2 ``` Response: ``` { "AccessGrantsInstanceArn": "arn:aws:s3:us-east-2: 111122223333:access-grants/default", "AccessGrantsInstanceId": "default", "CreatedAt": "2023-05-31T17:54:07.893000+00:00" } ``` ## Using the REST API For information about the Amazon S3 REST API support for managing an S3 Access Grants instance, see the following sections in the *Amazon Simple Storage Service API Reference*: + [https://docs.aws.amazon.com/AmazonS3/latest/API/API_control_ListAccessGrantsInstances.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_control_ListAccessGrantsInstances.html) ## Using the AWS SDKs This section provides examples of how to get the details of an S3 Access Grants instance by using the AWS SDKs. To use the following examples, replace the `user input placeholders` with your own information. ------ #### [ Java ] **Example – List all S3 Access Grants instances for an account** This action lists the S3 Access Grants instances for an account. You can only have one S3 Access Grants instance per Region. This action can also list other cross-account S3 Access Grants instances that your account has access to. ``` public void listAccessGrantsInstances() { ListAccessGrantsInstancesRequest listRequest = ListAccessGrantsInstancesRequest.builder() .accountId("111122223333") .build(); ListAccessGrantsInstancesResponse listResponse = s3Control.listAccessGrantsInstances(listRequest); LOGGER.info("ListAccessGrantsInstancesResponse: " + listResponse); } ``` Response: ``` ListAccessGrantsInstancesResponse( AccessGrantsInstancesList=[ ListAccessGrantsInstanceEntry( AccessGrantsInstanceId=default, AccessGrantsInstanceArn=arn:aws:s3:us-east-2:111122223333:access-grants/default, CreatedAt=2023-06-07T04:28:11.728Z ) ] ) ``` ------ # Associate or disassociate your IAM Identity Center instance In Amazon S3 Access Grants, you can associate the AWS IAM Identity Center instance of your corporate identity directory with an S3 Access Grants instance. After you do so, you can create access grants for your corporate directory users and groups, in addition to AWS Identity and Access Management (IAM) users and roles. If you no longer want to create access grants for your corporate directory users and groups, you can disassociate your IAM Identity Center instance from your S3 Access Grants instance. You can associate or disassociate an IAM Identity Center instance by using the Amazon S3 console, the AWS Command Line Interface (AWS CLI), the Amazon S3 REST API, and the AWS SDKs. ## Using the S3 console Before you associate your IAM Identity Center instance with your S3 Access Grants instance, you must add your corporate identity directory to IAM Identity Center. For more information, see [S3 Access Grants and corporate directory identities](access-grants-directory-ids.md). **To associate an IAM Identity Center instance with an S3 Access Grants instance** 1. Sign in to the AWS Management Console and open the Amazon S3 console at [https://console.aws.amazon.com/s3/](https://console.aws.amazon.com/s3/). 1. In the left navigation pane, choose **Access Grants**. 1. On the **S3 Access Grants** page, choose the Region that contains the S3 Access Grants instance that you want to work with. 1. Choose **View details** for the instance. 1. On the details page, in the **IAM Identity Center** section, choose to either **Add** an IAM Identity Center instance or **Deregister** an already associated IAM Identity Center instance. ## Using the AWS CLI To install the AWS CLI, see [Installing the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) in the *AWS Command Line Interface User Guide*. To use the following example command, replace the `user input placeholders` with your own information. **Example – Associate an IAM Identity Center instance with an S3 Access Grants instance** ``` aws s3control associate-access-grants-identity-center \ --account-id 111122223333 \ --identity-center-arn arn:aws:sso:::instance/ssoins-1234a567bb89012c \ --profile access-grants-profile \ --region eu-central-1 // No response body ``` **Example – Disassociate an IAM Identity Center instance from an S3 Access Grants instance** ``` aws s3control dissociate-access-grants-identity-center \ --account-id 111122223333 \ --profile access-grants-profile \ --region eu-central-1 // No response body ``` ## Using the REST API For information about the Amazon S3 REST API support for managing the association between an IAM Identity Center instance and an S3 Access Grants instance, see the following sections in the *Amazon Simple Storage Service API Reference*: + [https://docs.aws.amazon.com/AmazonS3/latest/API/API_control_AssociateAccessGrantsIdentityCenter.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_control_AssociateAccessGrantsIdentityCenter.html) + [https://docs.aws.amazon.com/AmazonS3/latest/API/API_control_DissociateAccessGrantsIdentityCenter.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_control_DissociateAccessGrantsIdentityCenter.html) # Delete an S3 Access Grants instance You can delete an Amazon S3 Access Grants instance from an AWS Region in your account. However, before you can delete an S3 Access Grants instance, you must first do the following: + Delete all resources within the S3 Access Grants instance, including all grants and locations. For more information, see [Delete a grant](https://docs.aws.amazon.com/AmazonS3/latest/userguide/access-grants-grant-delete.html) and [Delete a location](https://docs.aws.amazon.com/AmazonS3/latest/userguide/access-grants-grant-location.html). + If you've associated an AWS IAM Identity Center instance with your S3 Access Grants instance, you must disassociate the IAM Identity Center instance. For more information, see [Associate or disassociate your IAM Identity Center instance](https://docs.aws.amazon.com/AmazonS3/latest/userguide/access-grants-instance-idc.html). **Important** If you delete an S3 Access Grants instance, the deletion is permanent and can't be undone. All grantees that were given access through the grants in this S3 Access Grants instance will lose access to your S3 data. You can delete an S3 Access Grants instance by using the Amazon S3 console, the AWS Command Line Interface (AWS CLI), the Amazon S3 REST API, and the AWS SDKs. ## Using the S3 console **To delete an S3 Access Grants instance** 1. Sign in to the AWS Management Console and open the Amazon S3 console at [https://console.aws.amazon.com/s3/](https://console.aws.amazon.com/s3/). 1. In the left navigation pane, choose **Access Grants**. 1. On the **S3 Access Grants** page, choose the Region that contains the S3 Access Grants instance that you want to work with. 1. Choose **View details** for the instance. 1. On the instance details page, choose **Delete instance** in the upper-right corner. 1. In the dialog box that appears, choose **Delete**. This action can't be undone. ## Using the AWS CLI To install the AWS CLI, see [Installing the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) in the *AWS Command Line Interface User Guide*. To use the following example command, replace the `user input placeholders` with your own information. **Note** Before you can delete an S3 Access Grants instance, you must first delete all grants and locations created within the S3 Access Grants instance. If you have associated an IAM Identity Center center instance with your S3 Access Grants instance, you must disassociate it first. **Example – Delete an S3 Access Grants instance** ``` aws s3control delete-access-grants-instance \ --account-id 111122223333 \ --profile access-grants-profile \ --region us-east-2 \ --endpoint-url https://s3-control.us-east-2.amazonaws.com \ // No response body ``` ## Using the REST API For information about the Amazon S3 REST API support for deleting an S3 Access Grants instance, see [https://docs.aws.amazon.com/AmazonS3/latest/API/API_control_DeleteAccessGrantsInstance.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_control_DeleteAccessGrantsInstance.html) in the *Amazon Simple Storage Service API Reference*. ## Using the AWS SDKs This section provides examples of how to delete an S3 Access Grants instance by using the AWS SDKs. To use the following example, replace the `user input placeholders` with your own information. ------ #### [ Java ] **Note** Before you can delete an S3 Access Grants instance, you must first delete all grants and locations created within the S3 Access Grants instance. If you have associated an IAM Identity Center center instance with your S3 Access Grants instance, you must disassociate it first. **Example – Delete an S3 Access Grants instance** ``` public void deleteAccessGrantsInstance() { DeleteAccessGrantsInstanceRequest deleteRequest = DeleteAccessGrantsInstanceRequest.builder() .accountId("111122223333") .build(); DeleteAccessGrantsInstanceResponse deleteResponse = s3Control.deleteAccessGrantsInstance(deleteRequest); LOGGER.info("DeleteAccessGrantsInstanceResponse: " + deleteResponse); } ``` ------