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

Step 2: Select the application you are interested in by clicking its

name, if not the one already selected

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 applications 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 requestit 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! Lets catch our breath, shall we?! Well 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!), well also explain whats happening under the hood by both the API Developer Portal
UI and your applications OAuth 2.0 client library so you understand the end-to-end API request
process completely.

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)

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:

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: <Token Request Authorization Header>
d. Payload:
i. grant_type=password
ii. username=<Rakuten LinkShare Username>
iii. password=<Rakuten LinkShare Password>
iv. scope=<Rakuten LinkShare ID>

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):

Congratulations!
In case you didnt 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.

[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 applications 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

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: <Token Request Authorization Header from Step #3>
d. Payload:
i. grant_type=refresh_token
ii. refresh_token=<Refresh Token value also provided in the response to the
Web Service request from Step #4>
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):

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.