Tokens API Use Case Guide
Use the Restricted Data Token for secure access to Selling Partner APIs.
API Version: 2021-03-01
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. For definitions, refer to Terminology.
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.
Terminology
-
Restricted Data Token (RDT). A short-lived access token that authorizes calls restricted operations. An RDT remains valid for one hour.
-
Restricted operation. An operation that returns restricted data, such as PII. You need an RDT to call a restricted operation.
-
Restricted resource. An HTTP method and path that represent a restricted operation.
-
Restricted report type. A report type that contains PII. Refer to Restricted report types.
-
Delegator application. An application that gets an RDT and passes it to a delegatee application. The selling partner authorizes and interacts with the delegator application.
-
Delegatee application. An application that gets authorization to call restricted operations from an RDT that is passed to it by a delegator application. A delegatee application performs a specialized function that requires PII, such as shipping, tax invoicing, or tax remittance services, and is not directly authorized by the selling partner.
-
Specific path. A path in a restricted resource that contains a specific order or shipment identifier. For example,
orders/v0/orders/902-3159896-1390916/address
-
Generic path. A path in a restricted resource that contains a generic identifier, such as
{orderId}
or{shipmentId}
. For example,orders/v0/orders/{orderId}/address
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
Notes.
- The
getReportDocument
operation is considered a restricted operation only when a restricted report type is specified. Refer to the list of restricted report types. - When calling the
createRestrictedDataToken
operation to get an RDT for thegetReportDocument
operation, the specified restricted resource can contain only a specific path, not a generic path. For definitions, refer to Terminology. - 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.
- The
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
Tutorial: Get authorization to access restricted report types with PII information
-
The
getReportDocument
operation is considered a restricted operation only when a restricted report type is specified. Refer to the list of restricted report types. -
When calling the
createRestrictedDataToken
operation to get an RDT for thegetReportDocument
operation, the specified restricted resource can contain only a specific path, not a generic path. For definitions, refer to Terminology.
Prerequisites
To complete this tutorial, you will need:
-
Authorization from the selling partner for whom you are making calls. Refer to Authorizing Selling Partner API applications for more information.
-
Approval for the following roles:
- Direct-to-consumer shipping. Required to access shipping address information.
- Tax remittance. Required to access buyer information.
- Tax invoicing. Required to access buyer information.
To request access to these roles, refer to Registering as a developer and update your developer profile.
Step 1. Get an RDT
- Call the
createRestrictedDataToken
operation, passing the following parameters:
Body parameter:
Parameter | Description | Required |
---|---|---|
restrictedResources | A list of restricted resources. Note: Growth in the number of restricted resources results in growth in the size of the resulting restricted data token. The maximum size of the restricted data token before encoding and encryption cannot exceed 7kb without risk of failure when the token is employed. When requesting multiple resources, make sure that the resources requested are valid for the selling partner account type. For example, if requesting an RDT token for a seller, do not include vendor specific APIs in the createRestrictedDataToken request call. Type: < RestrictedResource > array |
Request Example
POST https://sellingpartnerapi-na.amazon.com/tokens/2021-03-01/restrictedDataToken
{
"restrictedResources": [
{
"method": "GET",
"path": "/reports/2021-06-30/documents/amzn1.spdoc.1.4.eu.dca0cb77-4733-4769-8476-f09bc32be2af.T1KIM200NIMFNU.1234"
}
]
}
Response
A successful response includes the following:
Name | Description |
---|---|
restrictedDataToken | A Restricted Data Token (RDT). This is a short-lived access token that authorizes calls to restricted operations. Pass this value with the x-amz-access-token header when making subsequent calls to these restricted resources. The size of the RDT is relative to the number of restricted resources specified in the request. The maximum size of the restricted data token before encoding and encryption cannot exceed 7kb without risk of failure when the token is employed. Type: string |
expiresIn | The lifetime of the Restricted Data Token, in seconds. Type: integer |
Response Example
{
"restrictedDataToken": "Atz.sprdt|IQEBLjAsAhRmHjNgHpi0U-Dme37rR6CuUpSR",
"expiresIn": 3600
}
- Save the
restrictedDataToken
value (the RDT) to provide it in thegetReportDocument
operation.
Tutorial: Get authorization to access PII for bulk orders
You can get an RDT that provides authorization to access Personally Identifiable Information (PII) for bulk orders. The dataElements
values that you specify (using the restrictedResources
parameter of the createRestrictedDataToken
operation) determine the type of restricted data that the RDT authorizes your application to access. In this tutorial we request an RDT that authorizes access to both buyer information and shipping address information.
Prerequisites
To complete this tutorial, you will need:
-
Authorization from the selling partner for whom you are making calls. Refer to Authorizing Selling Partner API applications for more information.
-
Approval for the following roles:
- Direct-to-consumer shipping. Required to access shipping address information.
- Tax remittance. Required to access buyer information.
- Tax invoicing. Required to access buyer information.
To request access to these roles, refer to Registering as a developer and update your developer profile.
Step 1. Get an RDT
Call the createRestrictedDataToken
operation to get an RDT.
- Call the
createRestrictedDataToken
operation, passing the following parameters:
Body parameter:
Parameter | Description | Required |
---|---|---|
restrictedResources
|
A list of restricted resources. Note:
Type: < |
Yes |
Request example
POST https://sellingpartnerapi-na.amazon.com/tokens/2021-03-01/restrictedDataToken
{
"restrictedResources": [
{
"method": "GET",
"path": "/orders/v0/orders",
"dataElements": ["buyerInfo", "shippingAddress"]
}
]
}
Response
A successful response includes the following:
Name | Description |
---|---|
restrictedDataToken
|
A Restricted Data Token (RDT). This is a short-lived access token that authorizes calls to restricted operations. Pass this value with the The size of the RDT is relative to the number of restricted resources specified in the request. The maximum size of the restricted data token before encoding and encryption cannot exceed 7kb without risk of failure when the token is employed. Type: string |
expiresIn
|
The lifetime of the RDT, in seconds. Type: integer |
Response example
{
"restrictedDataToken": "Atz.sprdt|IQEBLjAsAhRmHjNgHpi0U-Dme37rR6CuUpSR",
"expiresIn": 3600
}
- Save the
restrictedDataToken
value (the RDT) to use in Step 2. Include the RDT with a call to thegetOrders
operation
Step 2. Include the RDT with a call to the getOrders
operation
getOrders
operationCall the getOrders
operation of the Orders API, specifying the appropriate parameters to filter for the orders that you want. Be sure to include the RDT from Step 1. Get an RDT in the x-amz-access-token
header of your call to getOrders
. Because you specified both buyerInfo
and shippingAddress
in Step 1. Get an RDT, your call to getOrders
is authorized to return both buyer information and shipping address information for each order. Had you specified only buyerInfo
in Step 1, getOrders
would be authorized to return only buyer information for each order. Had you specified only shippingAddress
in Step 1, getOrders
would be authorized to return only shipping address information for each order.
Tutorial: Get authorization to access PII for the order items in an order
You can get an RDT that provides authorization to access Personally Identifiable Information (PII) in the order items in a specified order. In this workflow you specify dataElements
=buyerInfo
to indicate that the RDT will authorize your application to access buyer information for the order items.
Prerequisites
To complete this tutorial, you will need:
-
Authorization from the selling partner for whom you are making calls. Refer to Authorizing Selling Partner API applications for more information.
-
Approval for the following roles:
- Tax remittance
- Tax invoicing
Depending on your use case, you might need approval for only one of these roles. To learn more about roles and request access, refer to Registering as a developer and update your developer profile.
Step 1. Get an order ID
You need an order ID to identify an order for which you want order item information. You also need an order ID to get an RDT that authorizes your application to access buyer information for the order items. You can use the getOrders
operation of the Orders API to get a list of orders, from which you can get an order ID for the order that you are interested in.
-
Call the
getOrders
operation of the Orders API, specifying the appropriate parameters to filter for the order that you want.The operation returns orders that match your request. Each order includes an order ID.
-
From the orders that are returned, identify the order for which you want order item information.
-
Save the order ID for the order that you want, to use in Step 2. Get an RDT and Step 3. Include the RDT with a call to the
getOrderItems
operation.
Step 2. Get an RDT
Call the createRestrictedDataToken
operation to get an RDT. In the path
property of the restrictedResources
parameter, include the order ID from Step 1. Get an order ID. In this workflow we will specify the buyerInfo
value of the dataElements
parameter. This indicates that the RDT should provide authorization to access PII for use cases such as tax and gift wrapping.
Call the createRestrictedDataToken
operation to get an RDT.
- Call the
createRestrictedDataToken
operation, passing the following parameter:
Body parameter:
Parameter | Description | Required |
---|---|---|
restrictedResources
|
A list of restricted resources. Note:
Type: < |
Yes |
Request example
POST https://sellingpartnerapi-na.amazon.com/tokens/2021-03-01/restrictedDataToken
{
"restrictedResources": [
{
"method": "GET",
"path": "/orders/v0/orders/123-1234567-1234567/orderItems",
"dataElements": ["buyerInfo"]
}
]
}
Response
A successful response includes the following:
Name | Description |
---|---|
restrictedDataToken
|
A Restricted Data Token (RDT). This is a short-lived access token that authorizes calls to restricted operations. Pass this value with the The size of the RDT is relative to the number of restricted resources specified in the request. The maximum size of the restricted data token before encoding and encryption cannot exceed 7kb without risk of failure when the token is employed. Type: string |
expiresIn
|
The lifetime of the RDT, in seconds. Type: integer |
Response example
{
"restrictedDataToken": "Atz.sprdt|IQEBLjAsAhRmHjNgHpi0U-Dme37rR6CuUpSR",
"expiresIn": 3600
}
- Save the
restrictedDataToken
value (the RDT) to use in Step 3. Include the RDT with a call thegetOrder
operation.
Step 3. Include the RDT with a call to the getOrderItems
operation
getOrderItems
operationCall the getOrderItems
operation of the Orders API, specifying the order ID that you identified in Step 1. Get an order ID. Be sure to include the RDT from Step 1 in the x-amz-access-token
header of your call to getOrderItems
.
Tutorial: 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
- Calling the
createRestrictedDataToken
operation of the Tokens API (specifying the application ID of the delegatee application), - Getting an RDT from the
createRestrictedDataToken
response, and - 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. For definitions, refer to Terminology.
Prerequisites
To complete this tutorial, you will 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.
- Call the
createRestrictedDataToken
operation, passing the following parameters:
Body parameters:
Parameter | Description | Required |
---|---|---|
restrictedResources
|
A list of restricted resources. Note:
Type: < |
Yes |
targetApplication
|
The application ID for the target application to which access is being delegated. Type: string |
No |
Request example
POST https://sellingpartnerapi-na.amazon.com/tokens/2021-03-01/restrictedDataToken
{
"restrictedResources": [
{
"method": "GET",
"path": "/orders/v0/orders/123-1234567-1234567",
"dataElements": ["buyerInfo", "shippingAddress"]
}
],
"targetApplication": "amzn1.sellerapps.app.target-application"
}
Response
A successful response includes the following:
Name | Description |
---|---|
restrictedDataToken
|
A Restricted Data Token (RDT). This is a short-lived access token that authorizes calls to restricted operations. Pass this value with the The size of the RDT is relative to the number of restricted resources specified in the request. The maximum size of the restricted data token before encoding and encryption cannot exceed 7kb without risk of failure when the token is employed. Type: string |
expiresIn
|
The lifetime of the RDT, in seconds. Type: integer |
Response example
{
"restrictedDataToken": "Atz.sprdt|IQEBLjAsAhRmHjNgHpi0U-Dme37rR6CuUpSR",
"expiresIn": 3600
}
- 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
getOrder
operationThe 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.
- The delegatee application calls the
getOrder
operation, passing the following parameters:
Body parameters:
Parameter | Description | Required |
---|---|---|
orderId
|
An Amazon-defined order identifier, in 3-7-7 format. Type: string |
Yes |
Request example
GET https://sellingpartnerapi-na.amazon.com/orders/v0/orders/123-1234567-1234567
Response
A successful response includes the following:
Name | Description |
---|---|
payload
|
The payload for the Type: Order |
Response example
{
"payload": {
"AmazonOrderId": "902-3159896-1390916",
"PurchaseDate": "2017-01-20T19:49:35Z",
"LastUpdateDate": "2017-01-20T19:49:35Z",
"OrderStatus": "Pending",
"FulfillmentChannel": "SellerFulfilled",
"NumberOfItemsShipped": 0,
"NumberOfItemsUnshipped": 0,
"PaymentMethod": "Other",
"PaymentMethodDetails": [
"CreditCard",
"GiftCerificate"
],
"MarketplaceId": "ATVPDKIKX0DER",
"ShipmentServiceLevelCategory": "Standard",
"OrderType": "StandardOrder",
"EarliestShipDate": "2017-01-20T19:51:16Z",
"LatestShipDate": "2017-01-25T19:49:35Z",
"IsBusinessOrder": false,
"IsPrime": false,
"IsGlobalExpressEnabled": false,
"IsPremiumOrder": false,
"IsSoldByAB": false,
"DefaultShipFromLocationAddress": {
"Name": "MFNIntegrationTestMerchant",
"AddressLine1": "2201 WESTLAKE AVE",
"City": "SEATTLE",
"StateOrRegion": "WA",
"PostalCode": "98121-2778",
"CountryCode": "US",
"Phone": "+1 480-386-0930 ext. 73824",
"AddressType": "Commercial"
},
"FulfillmentInstruction": {
"FulfillmentSupplySourceId": "sampleSupplySourceId"
},
"IsISPU": false,
"ShippingAddress": {
"Name": "Michigan address",
"AddressLine1": "1 Cross St.",
"City": "Canton",
"StateOrRegion": "MI",
"PostalCode": "48817",
"CountryCode": "US"
},
"BuyerInfo": {
"BuyerEmail": "[email protected]",
"BuyerName": "John Doe",
"BuyerTaxInfo": {
"CompanyLegalName": "A Company Name"
},
"PurchaseOrderNumber": "1234567890123"
}
}
}
- The delegatee application uses the data in the response to perform its shipping and tax functions.
Tutorial: Get authorization to access shipment information for multiple shipments
You can get an RDT that provides authorization to get shipment information for any of a selling partner's shipments.
Prerequisites
To complete this tutorial, you will need:
-
Authorization from the selling partner for whom you are making calls. Refer to Authorizing Selling Partner API applications for more information.
-
Approval for the Direct-to-consumer shipping role, which is required to access shipping address information. To request access to this role, refer to Registering as a developer and update your developer profile.
-
Shipment IDs for the shipments that you want to get shipment information for.
Step 1. Get an RDT
Call the createRestrictedDataToken
operation to get an RDT. In the path
property of the restrictedResources
parameter that you specify, use a generic path that includes this text: {shipmentId}
. For definitions, refer to Terminology.
- Call the
createRestrictedDataToken
operation, passing the following parameter:
Body parameters:
Parameter | Description | Required |
---|---|---|
restrictedResources
|
A list of restricted resources. Note:
Type: < |
Yes |
Request example
POST https://sellingpartnerapi-na.amazon.com/tokens/2021-03-01/restrictedDataToken
{
"restrictedResources": [
{
"method": "GET",
"path": "/mfn/v0/shipments/{shipmentId}"
}
]
}
Response
A successful response includes the following:
Name | Description |
---|---|
restrictedDataToken
|
A Restricted Data Token (RDT). This is a short-lived access token that authorizes calls to restricted operations. Pass this value with the The size of the RDT is relative to the number of restricted resources specified in the request. The maximum size of the restricted data token before encoding and encryption cannot exceed 7kb without risk of failure when the token is employed. Type: string |
expiresIn
|
The lifetime of the RDT, in seconds. Type: integer |
Response example
{
"restrictedDataToken": "Atz.sprdt|IQEBLjAsAhRmHjNgHpi0U-Dme37rR6CuUpSR",
"expiresIn": 3600
}
-
Save the
restrictedDataToken
value (the RDT) to use in Step 2. Include the RDT with a call thegetShipment
operation.For definitions, refer to Terminology.
Step 2. Include the RDT with a call the getShipment
operation
getShipment
operationCall the getShipment
operation of the Merchant Fulfillment API, using the generic path that you specified in Step 1. Get an RDT and replacing {shipmentId}
with a real shipment ID from the selling partner. For example, GET /mfn/v0/shipments/FBA1234ABC5D
. Repeat this step for all of the shipments for which you want shipping information, specifying the appropriate shipment ID with each call. Each call must include the RDT from Step 1. Get an RDT in the x-amz-access-token
header.
Note. An RDT remains valid for one hour.
Tutorial: 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
-
Run
mvn package
inside the generated SDK folder. -
Download any of the following files and use them to build classes inside the
main/java/sampleCode/
folder of the generated client library. For definitions, refer to Terminology.- 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.
Updated about 1 month ago