Authentication

Gemini supports the OAuth 2.0 protocol.

Yahoo Gemini API uses OAuth 2.0 as a simple and secure method for validation and access. The authorization model is open and based on existing standards, which ensure that secure credentials can be provisioned and verified by different software platforms.

OAuth 2.0 allows you, and visitors to your web page, to securely access the Yahoo! Web, Image, and News content. As a publisher, OAuth 2.0 provides secure access to this content, using your Gemini API application ID and the Yahoo API key to verify your authorized access privileges and allow for correct billing from Yahoo.

Before You Begin

Follow these steps:

  1. To begin, you need a Yahoo user ID that is dedicated to Gemini. If you don’t have one (login.yahoo.com or admanager.yahoo.com), you should create one.
  2. Create the app and subsequent developer keys:
  • https://developer.yahoo.com/apps/create/?api=admg
  • If you are creating a web application for other companies to use your software to access Gemini, select Web Application as the app type. You will need a valid callback domain.
  • If you are creating a server-only connection to perform API functions restricted to your own company, use Installed Application. This does not require a callback domain to be entered; leave this blank. For subsequent API calls that require a callback url, simply enter oob.
  1. Next, you need to follow the explicit grant flow.
  2. Implicit grant flow only allows a single API session for each authorization.

Using OAuth 2.0 with Gemini API

Once your users connect with Gemini OAuth, your application will be able to make API calls on their behalf without requiring additional authorization from them.

The workflow is as follows:

  1. When users connect to Yahoo Gemini to create and manage ad campaigns, or query and fetch reports, you must send them to Yahoo! with the client_id you received when registering your app.
  2. Users are then prompted to connect to their Gemini account. After connecting, they will be redirected to your redirect_uri with an authorization code. If authorization is denied, an error code is returned.

Important

The callback domain registered when creating an app must match the callback domain used in the API request call. The subdomain of the redirect_uri is no longer accepted. If a callback URL is involved, make sure it is encoded when passed as part of the redirect_uri parameter. For example, if the callback URL is http://www.example.com, use redirect_uri=https%3A%2F%2Fwww.example.com.

  1. You can then exchange that authorization code for an access token, which enables usage of your API calls.

Setting Up Your OAuth 2.0 Client

For information on how to set up your OAuth 2.0 client, refer to the OAuth 2.0 Guide. OAuth 2.0 is an updated version of the OAuth protocol that supersedes OAuth 1.0 and 1.0a.

Some key changes and distinctions from OAuth 1.0:

  • SSL for secure communication
  • signatures are no longer necessary
  • support for a variety of grant types and flows

For detailed information on Yahoo!’s implementation of the OAuth standard, see the documentation OAuth Authorization Model on the Yahoo! Developer Network (YDN).

OAuth Refresh Tokens

Key points to consider when working with refresh tokens:

  • Refresh tokens will not expire. They can only be invalidated explicitly by the user.
  • Access tokens will expire after 60 minutes.
  • As a best practice, you should always capture the refresh token after using it to get a new access token. It may change, and when it does you should use the new one.
  • If you change your password, the existing refresh token should continue to work. A new refresh token will not be issued and you won’t need to request user consent and restart the OAuth flow.
  • If, as a Yahoo Partner, you explicitly revoke the OAuth access for your app on account info, you should request user consent again.

Best Practices

For authentication, access to the Gemini API and setup, follow these best practices:

  1. Create a dedicated Yahoo username just for Gemini API access (http://login.yahoo.com).
  2. While creating a new Yahoo account, use a real value as Date of Birthday. This information cannot be modified forward for security reasons. A wrong value can generate issues during the API configuration.
  3. Make sure that the Gemini API Read/Write permissions were checked when creating a new APP (https://developer.yahoo.com/apps/create/?api=admg).
  4. Ask your Account Manager to create a Reseller account for you. Doing so is useful if you want to create sub-accounts via the API, if you need to manage and retrieve advertiser data for your child accounts, or if you want to have your child accounts spend aggregated into to one single bill.
  5. For Resellers, create a test reseller account in production for testing purposes, as the Sandbox will not work for reseller accounts.
  6. Access tokens expire in 60 minutes. Store the refresh tokens in a database so that they can be used programmatically to get new access tokens.
  7. Remember to change the authorization header from Basic to Bearer when you make actual API calls.

FAQs

Can I use the same token information as my current Yahoo USA account to gain API access for a new Yahoo UK account?

Yes. You can use the same token/YUID to connect to a Yahoo UK account and pull reporting from that account. Make sure the UK account has the US YUID for the users to have access.

Note that this is a common behavior and applies to any region, not just the UK.

Can I use just one key for both GoW iOS and GoW Android?

Yes. You just need one API key for all of Gemini. We validate access based on the user who authenticates with this key, so you can use this key to perform actions on behalf of whatever accounts to which you have access.

Should a user create a Yahoo id to access Yahoo Gemini?

Yes. A user should create their own Yahoo User ID (YUID) to access Yahoo Gemini, if they don’t already have one.

Visit login.yahoo.com for more information about Yahoo User ID (YUID) Creation.

Note that this YUID should be the same User ID you use to log in to Yahoo Gemini.

Learn More

For more information, see Authorization Code Flow for Server-side Apps on the Yahoo! Developer Network (YDN).