Yahoo! JAPAN Ads API | Developer Center

About OAuth2.0

To manipulate data in an ad account using Yahoo! JAPAN Ads API, the application must be authorized by OAuth2.0. The authentication uses Yahoo! JAPAN Business ID (Business ID) that has access to the ad account you want to manipulate data.

Summary

This page describes authorization and authentication for manipulating ad account data using the Yahoo! JAPAN Ads API.

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

・About the Code Flow for Authorization

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.(Manage account access)
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

The available ad accounts depend on which Business ID you authorize for Yahoo! JAPAN Ads API.

In Figure 2, User A, who has Edit access for MCC accout1 and ad account1 and 2, authorized the application. In this case, the application using a token authorized by the Yahoo! JAPAN Ads API specifies MCC Account 2 in base account can get, add, update, and delete the ad account1 and 2.

　　Figure 2. Case where user A authorized the application

When sending an API request after User B, who has Read-only access to the ad account3, authorizes the application and specifying Ad Account 3 in base account, you can only reference ad account3.
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, by specifying the root MCC in base account, if authorized by the tool administrator.
Please refer to the "Before you start" for specific pattern-by-pattern authentication.

About the Code Flow for Authorization

OAuth2.0 of Yahoo! JAPAN Ads API only provides authorization code flow.Other authorization 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.