Tokens API

You use the Tokens API to get a Restricted Data Token (RDT) for restricted resources.

Release notes

• September 21, 2022

To learn more about the terms that are used in this guide, refer to Terminology.

What is the Tokens API?

The Selling Partner API for Tokens (Tokens API) provides a secure way to access a customer's Personally Identifiable Information (PII). You can call the createRestrictedDataToken operation of the Tokens API to get a Restricted Data Token (RDT) for one or more restricted resources that you specify. Or, if you have a delegatee application, you can get an RDT from a delegator application owned by a developer that you work closely with (refer to Delegating authorization). In either case, an RDT authorizes you to make calls to operations that return restricted data.

When you call a restricted operation, you include an RDT in the x-amz-access-token header. This is in contrast to other Selling Partner API operations, where you include an LWA access token in the x-amz-access-token header. For more information, refer to Step 3. Add headers to the URI.

Delegating authorization

With the Tokens API, a delegator application can get an RDT that delegates authorization to access PII to a delegatee application. The delegator application is authorized by the selling partner and is the application that the selling partner interacts with. The delegatee application performs a specialized function that requires PII, such as shipping, tax invoicing, or tax remittance services. These two applications are owned by different developers and are closely integrated, such that the delegator application can securely transmit an RDT to the delegatee application. For more information about delegating authorization using an RDT, refer to Tutorial: Delegate authorization to access PII.

Restricted operations

Restricted operations return customers' Personally Identifiable Information (PII). You need an RDT to call a restricted operation.

Here is list of restricted operations, grouped by API:

Direct Fulfillment Orders API:

• getOrders
• getOrder

Direct Fulfillment Orders API v2021-12-28

• getOrders
• getOrder

Direct Fulfillment Shipping API:

• getShippingLabel
• getShippingLabels
• getPackingSlip
• getPackingSlips
• getCustomerInvoice
• getCustomerInvoices
• createShippingLabels

Direct Fulfillment Shipping API v2021-12-28

• getShippingLabel
• getCustomerInvoices
• getCustomerInvoice
• getPackingSlips
• getPackingSlip

Easy Ship API v2022-03-23

• createScheduledPackageBulk

Merchant Fulfillment API:

• getShipment
• cancelShipment
• cancelShipmentOld
• createShipment

Orders API:

• getOrders
• getOrder
• getOrderItems
• getOrderRegulatedInfo
• getOrderAddress
• getOrderBuyerInfo
• getOrderItemsBuyerInfo

Reports API:

• getReportDocument

📘

Note

• The getReportDocument operation is considered a restricted operation only when a restricted report type is specified. Refer to the list of restricted report type.

• When calling the createRestrictedDataToken operation to get an RDT for the getReportDocument operation, the specified restricted resource can contain only a specific path, not a generic path.
• When using RDT to access the getReportDocument operation, make sure your application has the correct right roles to access the report. Refer to Roles in the Selling Partner API for roles to reports mapping.

Shipment Invoicing:

• getShipmentDetails

Shipping API:

• getShipment

Restricted report types

Restricted report types contain PII. When specifying a restricted report type in a call to the getReportDocument operation, you must pass in an RDT with the call.

Here is a list of restricted report types:

• GET_AMAZON_FULFILLED_SHIPMENTS_DATA_INVOICING
• GET_AMAZON_FULFILLED_SHIPMENTS_DATA_TAX
• GET_FLAT_FILE_ACTIONABLE_ORDER_DATA_SHIPPING
• GET_FLAT_FILE_ORDER_REPORT_DATA_SHIPPING
• GET_FLAT_FILE_ORDER_REPORT_DATA_INVOICING
• GET_FLAT_FILE_ORDER_REPORT_DATA_TAX
• GET_FLAT_FILE_ORDERS_RECONCILIATION_DATA_TAX
• GET_FLAT_FILE_ORDERS_RECONCILIATION_DATA_INVOICING
• GET_FLAT_FILE_ORDERS_RECONCILIATION_DATA_SHIPPING
• GET_ORDER_REPORT_DATA_INVOICING
• GET_ORDER_REPORT_DATA_TAX
• GET_ORDER_REPORT_DATA_SHIPPING
• GET_EASYSHIP_DOCUMENTS
• GET_GST_MTR_B2B_CUSTOM
• GET_VAT_TRANSACTION_DATA
• SC_VAT_TAX_REPORT

Generate an SDK for the Tokens API

You can find steps describing how to generate an SDK for the Tokens API in Java or C# at the following:

• Generate a Java SDK with LWA token exchange
• Generate a C# SDK with LWA token generation and authentication

If you're using the Java SDK, you should also:

1. Run mvn package inside the generated SDK folder.

2. Download any of the following files and use them to build classes inside the main/java/sampleCode/ folder of the generated client library.

   • RestrictedDataTokenWorkflow.java. For getting an RDT and using it to authorize your own application to call one or more restricted operations.
   • DelegatedRestrictedDataTokenWorkflowForDelegator.java. For getting an RDT that delegates authorization to call restricted operations to a delegatee application.
   • DelegatedRestrictedDataTokenWorkflowForDelegatee.java. For a delegatee application that receives an RDT from a delegator application and uses it for authorization to call restricted operations.

🚧

Use the latest version of the Tokens API

Use the latest version of tokens_2021-03-01.json when generating your SDK to ensure that you are getting the latest functionality.

Use cases

The following use case examples are available for the Tokens API:

• Get authorization to access restricted report types with PII information: Get and use an RDT to access restricted report types.
• Get authorization to access PII for bulk orders: Get and use an RDT to access PII for bulk orders
• Get authorization to access PII for order items in an order: Get an order ID and RDT to access PII for order items in an order.
• Delegate authorization to access PII: Authorize a delegatee application to call restricted operations.
• Get authorization to access shipment information for multiple shipments: Get an RDT that provides authorization to get shipment information for any of a selling partner's shipments.

Roles

createRestrictedDataToken

Attribute	Value
Regions	NA, EU, FE
Required roles (need at least one)	Amazon Fulfillment Buyer Communication Buyer Solicitation Finance and Accounting Inventory and Order Tracking Pricing Product Listing Professional Services (Restricted) Selling Partner Insights Direct to Consumer Shipping (Restricted) Tax Invoicing (Restricted) Tax Remittance (Restricted)