Google OAuth verification rejected: why narrower scopes were right

We built the Google integrations, submitted them for OAuth verification, and got rejected. A product that holds your life has to connect to the places your life already is, and for most people that means a calendar and a spreadsheet, both of which belong to Google.

What we had asked for#

Full calendar access. Full spreadsheets access.

Those are the scopes you reach for when you are building the feature and not yet thinking about the permission. You want to read events and write events, so you ask for the calendar. You want to read a sheet and write a row, so you ask for spreadsheets.

The reviewer's objection was that we had asked for more than the feature needed, and reading it back, that was obviously true. "Full spreadsheets" grants access to every spreadsheet in the account, forever, including the ones belonging to whatever else that person does with their life. Our feature needed one file that the user chose.

The narrower version#

What we asked for, and what we ask for now

Full calendar

every calendar, its settings and who it is shared with.

`calendar.events`

create, read and update events, and nothing about the calendar itself. It is what two-way sync actually requires.

Full spreadsheets

every spreadsheet in the account.

`drive.file`

only the files the user picked. With Google's own file picker, you choose the sheet and we can see that sheet, and nothing around it.

Both changes took an afternoon. The verification round trip they saved us took considerably longer than that, which is the part I would like to have worked out in advance.

The consent screen is the landing page#

Narrowing the scopes made the feature easier to explain, and a feature that is easier to explain is easier to say yes to.

The old consent screen asked for something that made a careful person hesitate, and a careful person is exactly who this product is for. "See, edit, share and permanently delete all your spreadsheets" is a sentence that ends an installation. "See and edit the file you choose" does not.

We had been treating the permission prompt as an obstacle between the user and the feature. It is the first honest description of the product that person will ever read, written in a format they already trust, and it is worth optimizing the way you would optimize a landing page: by making the thing it describes smaller.

What integrations are for#

The temptation with integrations is to treat them as import pipes: pull everything in, own the copy, become the system of record.

That is the wrong model for a calendar. Nobody wants a second calendar. They want the one they have to show up where they are working, and changes to flow both ways without either side becoming the master.

So the sync goes whichever way you pick and stays deliberately narrow. Cards with due dates can go out to Google, and events can come in as cards. For a card that came from Google, the calendar is the source, and neither side holds anything hostage. It is the same promise the export makes, applied to data that was never ours to begin with.

What the rejection was actually worth#

I have been asked whether the verification process was painful. It took weeks and it blocked a launch, so yes.

It was also the only review this product has had from someone with no stake in it shipping. Every other check on our permissions was us, looking at our own work, with a feature we wanted to finish sitting on the other side of the decision. That is not a review.

I would rather have arrived here on my own. I did not. The thing that got us here was a stranger with no reason to be generous, reading one screen, and being right about it in a way I had failed to be for months.