google calendar insufficient permission: why an app says connected and reads nothing

you connect google calendar to an app. the app says connected. a week later you notice it has never once mentioned a meeting. somewhere underneath, every request it made came back with google calendar insufficient permission, and nothing told you.

that happened to a founder on underway this week. this piece explains why it happens, how to fix it in any app, and what underway now does so it cannot happen quietly again.

what google calendar insufficient permission means

when an app asks to read your calendar, google shows a consent screen. on many accounts that screen lists each permission with its own tick box: see your email address, see your calendar events, and so on. you can untick any of them and still press continue.

if the calendar box is left unticked, the sign-in still succeeds. the app gets a token, and can even find out who you are. but the token only carries the permissions you ticked. the first time the app asks for your events, google refuses with a 403 and a message about insufficient permission or insufficient authentication scopes. to the app's sign-in page, everything worked. to the part of the app that reads your day, nothing ever does.

it is an easy box to miss. the screen is google's, not the app's, the boxes are small, and most people press continue on anything that looks like a permissions list.

how to fix it in any app

• open the app's settings and disconnect google calendar, so the old token is thrown away.
• connect it again, and on google's screen tick every box the app asks for, especially the one about your calendar events.
• if google does not show the boxes again, open your google account's third-party connections page, remove the app there, and connect once more.

there is no way to add a permission to a token that already exists. a new sign-in with the box ticked is the only fix.

why connected is not the same as working

most apps, underway included until today, decide a tool is connected at the moment you connect it. a key is accepted once, or a sign-in comes back once, and the badge goes green for good. after that, reads fail in the background so that one broken tool cannot break the rest, which is right, and which also means a broken connection looks exactly like a quiet one.

keys get revoked. sign-ins run out. someone rotates a password. a permission box gets unticked. none of it shows up as a red badge unless something goes and checks.

what underway does now

underway reads the tools you already work in, your calendar, your meeting notetaker, your commits, your payments, so the questions in each episode know what actually happened that day. so it now checks every one of those connections, straight after you connect it and then once an hour, with the smallest request each tool allows.

• google calendar can no longer be connected with the calendar box unticked. you are asked to try again and allow each permission, instead of being told it worked.
• when a check finds a tool refusing, its square on context shows an ! where the tick was, and its panel says what went wrong and the one step that fixes it: tick the calendar box, make a new key, or sign in again.
• today shows a connection needs you, with a fix button that opens that tool.
• you get one email saying the same thing, once per problem. if it breaks again after you fix it, you hear about it again.
• a tool that could not be reached at all, because of an outage, is left alone. only a refusal is yours to fix.

meeting notetakers got a second fix. a new fathom account comes with a sample call recorded years ago, and it was arriving in founders' days as if it had happened that morning. recordings from long before the read are now left out.

all of it is the same on the phone: the mark on the square, the card on today and the step that fixes it.

faq