Acquiring your Access Token Introduction Welcome to the Rakuten Marketing API Developer Portal! The new API Developer Portal leverages an OAuth 2.0 access token to authenticate Web Service requests. To learn more about the OAuth 2.0 protocol and find code to further help you implement this request process automatically, please visit oauth.net/2/. Client libraries are available for most modern programming languages. This very simple guide will demonstrate both how to acquire an access token through the User Interface and through Web Service requests. It assumes you have created an application in the API Developer Portal and subscribed at least one Rakuten Marketing Web Service to it. Should you require it, please reference the Getting Started Guide in the footer of the portal for a more complete walkthrough that includes these steps and additional details on how to make API requests to subscribed Rakuten Marketing Web Services. This guide uses the popular free Chrome Browser App, Advanced REST Client but any Web Services client that allows you to send headers with a POST request should suffice.
Step 1: Go to My Subscriptions
1
Step 2: Select the application you are interested in by clicking its name, if not the one already selected
2
Step 3: Click Generate to create Consumer Key and Consumer Secret A little background info: The Consumer Key (sometimes called ‘Client ID’) and Consumer Secret (sometimes called ‘Client Secret’) are unique to each API Developer Portal application. These keys are combined by your application’s OAuth2.0 client library to create the Token Request Authorization header2 (we like saving you time, so the Portal also provides you with this header). This header is submitted with the access token request. The access token is what allows your application to make API Requests to our system without having to resubmit the username, password, and ID with each request—it has a lifespan of 60 minutes. When that token expires your application will automatically request a new one prior to making another successful API request. Woah, woah, woah! Let’s catch our breath, shall we?! We’ll not only provide you with a super easy Web-based solution to acquiring an access token that you can use to test your recently subscribed API(s) in a matter of minutes (seconds, if you are one of those lucky speed readers!), we’ll also explain what’s happening under the hood by both the API Developer Portal UI and your application’s OAuth 2.0 client library so you understand the end-to-end API request process completely.
2
The Token Request Authorization header consist of the word ‘Basic’ followed by a space and the Base64-encoded Consumer Key:Consumer Secret (e.g. echo –n 3y1VPK4Wb7PgjaHacowRGy_HyZca:pCdxrsjf57nVtFXBs5fa2gzYHQwa|base64)
3
Step 4: Request an Access Token to generate the API Request Authorization header Choose your own adventure! In Step #4 and optional Step #5 we describe two available approaches to provide both simplicity for testing and enough details for your backend integration. How this can be done in the API Developer Portal User Interface: 1. Click “Acquire an access token to make requests to the subscribed Web Services below!” 2. When prompted, enter the Username, Password, and ID (SID/MID) for the user you want to make Web Service requests and then click Submit. The account provided should be one existing in the Dashboard and can be for any valid user with access to the ID (it can be the same as the account used to login to the API Developer Portal):
3. Click the button to copy the API Request Authorization header to the Clipboard:
4
How this can be done through a Web Service request: 1. Configure your application or favorite Web Service client (e.g. Advanced Rest Client) to make the following request: a. URL: https://api.rakutenmarketing.com/token b. HTTP Verb: POST c. Headers: i. Authorization: d. Payload: i. grant_type=password ii. username= iii. password= iv. scope=
2. Submit your request and store the access token value provided in the results (you will prepend “Bearer “ to create the API Request Authorization header used later):
5
Congratulations! In case you didn’t know…
You have now acquired your access token!! You can use this access token to make API requests for 60 minutes. After that time the access token will expire and you will need a new API Request Authorization header to make additional API requests. This typically happens automatically through your OAuth2.0 client library. If you want to make an API request as a different user or get a new token prior to expiration [resetting the token expiration in the process], take a look at Step #5 below. Please Note: Various API Developer Portal Web Services require that legacy tokens have been generated in the Dashboards; this is required to support both direct API and Portal API access in parallel during the transition period. For Publishers, the legacy tokens can be generated in the Links->Web Services section of the Publisher Dashboard for the SID being requested. The Web Services Token is used behind the scenes but not in any API Developer Portal-facing request. The Security Token is used as a parameter for the Advanced Reports API to provide additional security. For Advertisers, the API Key can be found in the Reports->Create a Custom Report section of the Advertiser Dashboard for the MID being requested.
6
[OPTIONAL] Step 5: acquire a new Access Token and API Request Authorization Header prior to Access Token expiration How this can be done in the API Developer Portal User Interface: 1. 2. 3. 4.
Return to My Subscriptions Select the appropriate application to expand its details Select Show Keys to show the application’s production keys Click the refresh arrow button to prompt for new API user credentials:
5. Enter Username, Password, and ID (SID/MID) for the user you want to make Web Service requests. You can provide the same account used in Step #4 or a different one configured in the Dashboard. Upon Submit, the access token will be updated in the appropriate API Request Authorization header and the expiration will reset 6. You can now copy the API Request Authorization header and use it to make additional API requests
7
How this can be done through a Web Service request: 1. Configure your application or favorite Web Service client (e.g. Advanced Rest Client) to make the following request: a. URL: https://api.rakutenmarketing.com/token b. HTTP Verb: POST c. Headers: i. Authorization: d. Payload: i. grant_type=refresh_token ii. refresh_token= iii. scope=Production
2. Submit your request and store the access token value provided in the results (Reminder: you will prepend “Bearer “ to create the API Request Authorization header):
8
Conclusion You made it! You know everything that you need to know about making access token requests through the API Developer Portal, but should you be on a roll and/or ready to invest even more time to getting the most out of the Rakuten Marketing platform, please consider reviewing the documentation associated with each API you are interested in for more information on request parameters, samples responses, and error messages. If after this review you should have any additional questions or challenges, please do not hesitate to reach out to us through your preferred Rakuten Marketing support channel.
9
