Delegate authorization to access PII

Learn how to use the Tokens API to delegate authorization to access PII. You can delegate authorization to call restricted operations to a "delegatee application," which is an application that performs a specialized function for a selling partner (such as shipping, tax invoicing, or tax remittance services) but is not directly authorized by the selling partner. You delegate authorization in this way by

1. Calling the createRestrictedDataToken operation of the Tokens API (specifying the application ID of the delegatee application),
2. Getting an RDT from the createRestrictedDataToken response, and
3. Passing the RDT to the delegatee application.

The RDT authorizes the delegatee application to call restricted operations that return the PII required to perform functions on behalf of the selling partner.

Prerequisites

To complete this tutorial, you need:

• Authorization from the selling partner for whom you are making calls. Refer to Authorizing Selling Partner API applications for more information.
• To have indicated in the App registration form that you want to delegate access to PII to another application. For instructions for updating the App registration form, refer to Registering your application. Indicate in the form the types of PII that you want to delegate.
• The order ID for an order that requires shipping or tax functionality.
• A partnership with a developer with a delegatee application.
• The application ID of the delegatee application.
• A secure means to transmit an RDT and an order ID to a delegatee application.

In addition, the developer with the delegatee application in Step 3. The delegatee application calls the getOrder operation will need to:

• Register as a developer, requesting approval for the roles that are required to access buyer information and shipping address information. These are:

  • Direct-to-consumer shipping. Required to access shipping address information.
  • Tax remittance. Required to access buyer information.
  • Tax invoicing. Required to access buyer information.

  For more information about roles, refer to Roles in the Selling Partner API.

Step 1. Get an RDT

Call the createRestrictedDataToken operation to get an RDT. In the path property of the restrictedResources parameter, include the order ID of the order for which PII is required. In this workflow we will specify both the buyerInfo and shippingAddress values of the dataElements parameter. This indicates that the RDT should include authorization to access PII for use cases such as tax and shipping. In your own workflow you might specify only one value, depending on the PII your use case requires.

1. Call the createRestrictedDataToken operation.
2. Save the restrictedDataToken value (the RDT) to provide to the delegatee application in the following step.

Step 2. Pass the RDT and order ID to the delegatee application

Securely transmit the RDT and order ID to the delegatee application. The application will use these when calling the getOrder operation in the following step.

Step 3. The delegatee application calls the getOrder operation

The delegatee application calls the getOrder operation of the Orders API, specifying in the path the order ID from Step 2. Pass the RDT and order ID to the delegatee application. The call must include the RDT (also from Step 2) in the x-amz-access-token header of the call. Because both buyerInfo and shippingAddress were specified in Step 1. Get an RDT, the call to getOrder returns both buyer information and shipping address information for the order.

1. The delegatee application calls the getOrder operation.
2. The delegatee application uses the data in the response to perform its shipping and tax functions.