About OAuth2.0

In Yahoo! JAPAN Ads API, an application must be authorized by OAuth2.0. Authentication will be done with Yahoo! JAPAN Business ID, hereinafter referred to as "Business ID".


Relation of Yahoo! JAPAN Ads API and Yahoo! JAPAN Business ID.


In Yahoo! JAPAN Ads, Read-only/Edit access roles of the account will be set for each Business ID.(Mechanism of User/Roles)
For that reason, the available ad accounts to operate, and operations that can be performed may differ per Business ID.

  Figure 1. Example of accounts

Similarly, in Yahoo! JAPAN Ads API, the available API may differ depending on the authorized Business ID.

Figure 2 shows the case where user A authorized the application. In this case, Yahoo! JAPAN Ads API can get, add, update and delete the account (1) and (2).

  Figure 2. Case where user A authorized the application


When sending an API request with the authorization of user B, only ad account (3) can be referenced.
In Yahoo! JAPAN Ads API, the user can only request GET operation (excluding reports and exports ), if they do not have edit/update role.

The following error will occur, if the API request is sent without the read or update permission of ad accounts.

-HTTP Status code: 403
-Error code: 0098
-Error message: Permission denied.

You can get, add, update or delete every ad account under that company, if authorized by the tool administrator.
MCC account, it will be possible to operate API if it has permission, even if the account belongs to another company.


Coordinating Ad Accounts of Other Companies

  Figure 3. Example of coordinating other companies' ad account

For operating ad accounts owned by the other company, it will be possible if the application is authorized by the Business ID that holds the target account.


About the Code Flow for Authorization


OAuth2.0 of Yahoo! JAPAN Ads API only provides authorization code flow.Other authentication flow cannot be used. The authorization code flow will be explained below.

  

  Figure 4. Authorization code flow

In the authorization code flow of figure 4, if the company is advertiser/agency, "User" and "Application" will be the employees or the system of your own company with Yahoo! JAPAN Ads API contract.
In the case of Tool providers, the "Application" will be the system of your own company with Yahoo! JAPAN Ads API contract, but the "User" will be the advertisers/agencies of other company who holds their own Yahoo! JAPAN Business ID.

In authorization code flow, authorization and getting access tokens will be done with the following steps.


1. When the user starts using Yahoo! JAPAN Ads, the application will send authorization request to authorization server (/oauth/v1/authorize) via browser.
2. If the authorization server receives authorization request, the screen will be redirected to "Yahoo! JAPAN Business ID login screen".
3. The user will login with their Yahoo! JAPAN Business ID in "Yahoo! JAPAN Business ID login screen".
4. If the user logged-in successfully, the browser displays screen to approve the authorization of application.
5. If the user approves the authorization of application, the screen will be redirected to the redirect URI entered upon adding application.
6. Access token can be acquired by sending Auth code to authorization server (/oauth/v1/token). The refresh token will also be returned along the access token.
7. Send API request to Yahoo! JAPAN Ads API using the acquired access token.


Furthermore, the authorization code flow is a flow required for obtaining the first access token. If you have done the authorization once, you can reacquire the access token using the refresh token returned in step 6.
Refer to API call for more detailed steps of API call.