by Olivia S., Solutions Architect, Selling Partner Developer Services | September 19, 2022
If you are a developer who is building a new integration in Selling Partner API (SP-API), you might have come across a new term - roles. Roles are a mechanism in SP-API used to determine whether a developer or application has access to an operation or resources. This blog post will help you understand what roles are and how to select the roles you need for your profile and application.
Roles limit data access to ensure developers can only access data that is required for an application. Restricted roles protect personally identifiable information (PII) and other sensitive data by limiting access. As a developer, you must request and qualify for a particular role, or you will not be able to access the operations and resources grouped under that role.
When you register as a developer, you’ll notice that the Developer Profile form contains a section called Roles.
In the Roles section, you select the roles you need for your apps. For details on individual role definitions, refer to Roles in the Selling Partner API documentation.
The list of roles is long and it can be overwhelming. You may have trouble deciding which roles to select. This post is intended to help guide you.
To choose the correct roles for your developer profile, start by examining the list of API operations, feeds, reports, and notifications you currently use. Then search the Selling Partner API documentation for your chosen operation, feed, report, or notification to find which role grants access to this resource. For example, if you’re looking for a role that grants access to
SETTLEMENT_REPORT. Start by searching for
SETTLEMENT_REPORT. Notice that the Finance and Accounting role appears in the search results.
Next, navigate to the Feeds, Reports, and Notifications section of the Finance and Accounting role documentation and verify that
SETTLEMENT_REPORT is supported by this role. The
SETTLEMENT_REPORT is listed, so you can select Finance and Accounting as one of the roles in your Developer Profile.
Keep in mind that multiple roles can provide access to a single operation, report, or feed type, so do your research so you don’t end up applying for more roles than you need. For example, if you use Orders API and
GET_FLAT_FILE_ALL_ORDERS_DATA_BY_LAST_UPDATE_GENERAL, you would only need to apply for the Inventory and Order Tracking role.
Once you submit your developer profile, and have your profile approved, you still need to create an application before you can make SP-API calls.
When you fill out the App registration form, there is another section for Roles. As a developer, you might be creating multiple applications but not every application needs all the roles that you are approved for. For this reason, you must also select the roles for your specific application. Always keep in mind the least privilege principle and practice it where you can.
Navigate to the App registration form, fill out the fields, and select the business entity that your application supports. If you support both vendors and sellers, create an application for each business entity and select the roles that apply for each entity. Next select the roles that you need to apply to the application you’re registering.
If a role you are looking for is not listed on the App registration form, it means you haven’t applied for it in your Developer Profile. Go back a step, apply for the missing role through your Developer profile first, then come back to the App registration form.
For the full workflow and next steps refer to Registering your Application in the Developer Guide.
This blog post has outlined how to find role definitions in the documentation, how to determine which roles you need, and how to apply for roles in the developer profile and app registration workflows. If you’d like to read more about roles, you can refer to Roles in the Selling Partner API documentation. For any questions, check out the Roles FAQ section as well. Happy coding!
Have feedback on this post?
If you have questions or feedback on this post, we'd like to hear from you! Please vote and leave a comment using the tools at the bottom of this page.
Subscribe to updates via RSS feed.
Updated 2 months ago