How to access Google Spreadsheets with a service account credentials?

How to access Google Spreadsheets with a service account credentials?

  1. Blog
  2. 15 November 2026
  3. 4 min read

Stefan Bogdanescu

Founder & Senior Architect

The Ownership Gap: Why Service Accounts Can't See Private Sheets by Default

When building a server-side application in PHP to interact with Google Spreadsheets, developers often encounter a specific friction point regarding authentication scopes and ownership. You can successfully authenticate using OAuth 2.0, yet the API returns only the spreadsheets explicitly shared with your service account. This is not a bug; it is a direct consequence of how Google Cloud IAM separates user identity from machine identity.

To retrieve all spreadsheets owned by your main user account—including those that are strictly private and never explicitly shared with a service—you must bridge the gap between two distinct authentication models: User Delegation and Direct Service Account Access.

The Limitation of Raw Service Account Credentials

A standard service account JSON key file represents an impersonated identity within the Google Cloud ecosystem. When you mount these credentials directly into your PHP application using Google_Client or a similar library, the API calls originate from the service account's email address.

By default, this identity can only see resources it has been granted access to via sharing permissions. If a spreadsheet is owned by user@example.com and shared with service-account@project.iam.gserviceaccount.com, the service account sees it. However, if the owner creates a new sheet and keeps it private (visible only to themselves), the service account cannot see it, regardless of whether you have "full access" in your mind. The API strictly enforces the permission matrix against the identity making the request.

Implementing User Delegation

The solution is User Delegation via OAuth 2.0. This pattern allows your server-side application to act as an intermediary. Your PHP app authenticates as the end-user (the spreadsheet owner) and then, with that user's explicit consent or stored refresh token, requests access on their behalf.

Here is how the flow typically works in a PHP environment:

  1. Initial Consent: The user must log in through an OAuth 2.0 authorization URL, granting your app permission to access their Drive API scopes (e.g., https://www.googleapis.com/auth/drive).
  2. Token Exchange: Your backend exchanges the authorization code for an access token and a refresh token.
  3. Delegation Request: When you need to call the Sheets API, your PHP code requests a new access token using the stored refresh token, specifically asking to impersonate the service account's credentials if necessary, or simply using the user's token with the appropriate scopes.

In Google Cloud Console terminology, this often looks like enabling "Drive API" and "Sheets API" on the user's behalf. The critical distinction is that the OAuth 2.0 flow runs under the user's identity, not the service account's raw identity.

Handling Existing vs. New Spreadsheets

Your requirement to maintain privacy while giving a machine full access creates a specific architectural constraint. You want the spreadsheets to remain private to other humans but accessible to your application.

If you use User Delegation correctly:

  • Existing Sheets: Once the user grants consent, their OAuth token allows the app to read/write any sheet they own. The privacy setting remains "Owner only" for other users; the app sees them because it is technically acting as the owner via the delegated session.
  • New Sheets: When your PHP application creates a new spreadsheet using the delegated user credentials, ownership automatically belongs to the main account, not the service account. Consequently, these sheets will be private by default, exactly as you requested.

Implementation Nuances in PHP

When implementing this in PHP, ensure you are loading the correct scopes. You cannot use the standard service_account credential file alone for reading private user-owned files without User Delegation. Instead, your code logic should look like this:

use Google\Client;
use Google\Auth\HttpHandler\HttpClientCache;

$client = new Client();
$httpClient = HttpClientCache::build();

// Load the service account credentials to enable delegation (optional depending on specific flow)
// $serviceAccountCredentials = json_decode(file_get_contents('path/to/credentials.json'), true);

// Set the user's refresh token obtained from initial OAuth login
$client->setAccessToken($userRefreshToken); 

// Define scopes for Drive and Sheets
$scopes = [
    'https://www.googleapis.com/auth/drive.readonly', // or drive.file for full access
];
$client->addScope('https://www.googleapis.com/auth/spreadsheets');

// Request a token using the user's refresh token, potentially impersonating the service account context if needed
$accessToken = $client->fetchAccessTokenWithOAuth2($httpClient);

// Now you can use $client to list all owned spreadsheets
$service = new Google_Service_Sheets($client);
$spreadsheetList = $service->spreadsheets->listSpreadsheets();

The key takeaway is that the access_token fetched here represents the user, not the raw service account, allowing access to private files.

Trade-offs and Security Considerations

This approach introduces a dependency on managing refresh tokens securely. Since the application holds the user's token, you must store these tokens in a secure database or encrypted file system within your PHP backend. If this is a multi-user application (e.g., one app serving multiple users), you cannot share a single refresh token; each user requires their own authentication session.

Additionally, relying on User Delegation means the application can only access files for which it has an active, valid refresh token. You must implement logic to detect expired tokens and trigger a re-authentication flow if necessary.

For developers looking to streamline this OAuth 2.0 integration with robust Laravel support, checking resources like https://laravelcompany.com can provide insights into managing service providers within the framework. However, regardless of the framework used, understanding the IAM boundary between raw service accounts and user-delegated identities is non-negotiable for accessing private data.

Our network