:doc:`KMS <../../kms>` / Client / retire_grant

************
retire_grant
************



.. py:method:: KMS.Client.retire_grant(**kwargs)

  

  Deletes a grant. Typically, you retire a grant when you no longer need its permissions. To identify the grant to retire, use a `grant token <https://docs.aws.amazon.com/kms/latest/developerguide/grants.html#grant_token>`__, or both the grant ID and a key identifier (key ID or key ARN) of the KMS key. The  CreateGrant operation returns both values.

   

  This operation can be called by the *retiring principal* for a grant, by the *grantee principal* if the grant allows the ``RetireGrant`` operation, and by the Amazon Web Services account in which the grant is created. It can also be called by principals to whom permission for retiring a grant is delegated.

   

  For detailed information about grants, including grant terminology, see `Grants in KMS <https://docs.aws.amazon.com/kms/latest/developerguide/grants.html>`__ in the *Key Management Service Developer Guide* . For examples of creating grants in several programming languages, see `Use CreateGrant with an Amazon Web Services SDK or CLI <https://docs.aws.amazon.com/kms/latest/developerguide/example_kms_CreateGrant_section.html>`__.

   

  **Cross-account use**: Yes. You can retire a grant on a KMS key in a different Amazon Web Services account.

   

  **Required permissions**: Permission to retire a grant is determined primarily by the grant. For details, see `Retiring and revoking grants <https://docs.aws.amazon.com/kms/latest/developerguide/grant-delete.html>`__ in the *Key Management Service Developer Guide*.

   

  **Related operations:**

   

  
  *  CreateGrant
   
  *  ListGrants
   
  *  ListRetirableGrants
   
  *  RevokeGrant
  

   

  **Eventual consistency**: The KMS API follows an eventual consistency model. For more information, see `KMS eventual consistency <https://docs.aws.amazon.com/kms/latest/developerguide/accessing-kms.html#programming-eventual-consistency>`__.

  

  See also: `AWS API Documentation <https://docs.aws.amazon.com/goto/WebAPI/kms-2014-11-01/RetireGrant>`_  


  **Request Syntax**
  ::

    response = client.retire_grant(
        GrantToken='string',
        KeyId='string',
        GrantId='string',
        DryRun=True|False
    )
    
  :type GrantToken: string
  :param GrantToken: 

    Identifies the grant to be retired. You can use a grant token to identify a new grant even before it has achieved eventual consistency.

     

    Only the  CreateGrant operation returns a grant token. For details, see `Grant token <https://docs.aws.amazon.com/kms/latest/developerguide/grants.html#grant_token>`__ and `Eventual consistency <https://docs.aws.amazon.com/kms/latest/developerguide/grants.html#terms-eventual-consistency>`__ in the *Key Management Service Developer Guide*.

    

  
  :type KeyId: string
  :param KeyId: 

    The key ARN KMS key associated with the grant. To find the key ARN, use the  ListKeys operation.

     

    For example: ``arn:aws:kms:us-east-2:444455556666:key/1234abcd-12ab-34cd-56ef-1234567890ab``

    

  
  :type GrantId: string
  :param GrantId: 

    Identifies the grant to retire. To get the grant ID, use  CreateGrant,  ListGrants, or  ListRetirableGrants.

     

    
    * Grant ID Example - 0123456789012345678901234567890123456789012345678901234567890123
    

    

  
  :type DryRun: boolean
  :param DryRun: 

    Checks if your request will succeed. ``DryRun`` is an optional parameter.

     

    To learn more about how to use this parameter, see `Testing your permissions <https://docs.aws.amazon.com/kms/latest/developerguide/testing-permissions.html>`__ in the *Key Management Service Developer Guide*.

    

  
  
  :returns: None
  **Exceptions**
  
  *   :py:class:`KMS.Client.exceptions.InvalidArnException`

  
  *   :py:class:`KMS.Client.exceptions.InvalidGrantTokenException`

  
  *   :py:class:`KMS.Client.exceptions.InvalidGrantIdException`

  
  *   :py:class:`KMS.Client.exceptions.NotFoundException`

  
  *   :py:class:`KMS.Client.exceptions.DependencyTimeoutException`

  
  *   :py:class:`KMS.Client.exceptions.KMSInternalException`

  
  *   :py:class:`KMS.Client.exceptions.KMSInvalidStateException`

  
  *   :py:class:`KMS.Client.exceptions.DryRunOperationException`

  

  **Examples**

  The following example retires a grant.
  ::

    response = client.retire_grant(
        # The identifier of the grant to retire.
        GrantId='0c237476b39f8bc44e45212e08498fbe3151305030726c0590dd8d3e9f3d6a60',
        # The Amazon Resource Name (ARN) of the KMS key associated with the grant.
        KeyId='arn:aws:kms:us-east-2:444455556666:key/1234abcd-12ab-34cd-56ef-1234567890ab',
    )
    
    print(response)

  
  Expected Output:
  ::

    {
        'ResponseMetadata': {
            '...': '...',
        },
    }

  