The following table summarizes the list of credentials that an app should manage. Refer to our OAuth documentation to learn about various app types.
| Authentication workflow | Credential | Type of credential | Purpose |
|---|---|---|---|
| All app types | Developer Token | App credentials | Lets you use Google Ads API with an approved access level. |
|
Javascript web apps Android apps |
OAuth client ID | App credentials | Uniquely identifies the App when doing an OAuth flow. |
| Access token & refresh token | User credentials | Represents the user's authorization to let the app access their Google Ads account on their behalf. | |
|
Server-side web apps Desktop and iOS apps TV and Device apps |
OAuth client ID & client secret | App credentials | Uniquely identifies the App when doing an OAuth flow. |
| Access token & refresh token | User credentials | Represent the user's authorization to let the app access their Google Ads account on their behalf. | |
| Service accounts | OAuth service account key | App credentials | Used for signing the OAuth request. |
| Service account's access token | User credentials | Represents the service account's authorization. The user has shared their Google Ads account with the service account. |
There are a few points to consider when managing credentials for a Google Ads API app.
Handle app credentials securely
App credentials refer to settings that are specific to your app, and don't vary from one user to another. Treat your OAuth app credentials with extreme care, as they allow anyone who has them to use your app's identity to gain access to user information. Store your OAuth app credentials in a secure place and protect them, just as you would a password. Where possible, use a secrets manager, such as Google Cloud Secret Manager to store app credentials. You must never commit client credentials into publicly available code repositories. We highly recommend that you avoid committing them to any code repository.
Handle user credentials securely
User credentials refer to OAuth tokens that represent the user's authorization. They are entrusted to you by users who give you permission to act and access data on their behalf -- either directly by authenticating your app, or indirectly by sharing their Google Ads account with your service account. Never transmit tokens in plaintext, and always store encrypted tokens at rest to provide an extra layer of protection in the event of a data breach. Revoke tokens or service account permissions when you no longer need access to a user's account. After the tokens are revoked, delete them permanently from your application or system.
Handle refresh token revocation and expiration
If you are using a user authentication flow, then you should keep in mind that refresh tokens can be invalidated at any time. For example, if you are using a multi-user authentication flow, the user could choose to revoke access to your app. While an app that uses single-user authentication flow is less likely to be affected this way, a manual or automated process designed to protect users also could still purge the refresh token, or the refresh token could expire. If your app requires notification of token revocation to provide a good experience for users, you must integrate with our Cross-Account Protection service.
Reuse user credentials across your API requests
OAuth access tokens are short-lived and expire in an hour. If you use our client libraries, the access token expiry and refreshes are taken care of for you in a thread-safe manner. All you need to do is to construct a Google Ads API session object with the appropriate OAuth credentials and reuse it throughout its lifetime.
If you build your own access token refresh and management strategy, then you should keep track of the access token expiry and reuse it as much as possible. If you don't know when an access token was last refreshed, you could attempt to refresh it, assuming it has already expired. If the access token is not close to lapsing, the server returns the same access token, along with the milliseconds remaining until the token expires. We recommend forcing an access token refresh if there's less than 5 minutes until expiration.