Scopes

A scope is one question your app may ask. Users grant them individually, so expect to hold fewer than you requested.

Ask for the fewest that make your product work. Every extra scope is another line on the consent screen and another reason to decline.

Choosing a tier

Ask yourself: would an answer do?

If you're drawing a moving dot on a map, you need coordinates, and the sensitive tier is the honest choice. If you're sending a notification, tagging a photo, unlocking something, or checking a transaction, an answer will do.

If you do take the sensitive tier, two things come with it: every call names a registered purpose the user reads, and the access ends on a date the user picks, at most 90 days out. See Two expiries.

Three common mistakes:

• Using location.latest.read to check proximity. Use location.verify.zone. You get inside or outside without holding a position.
• Using location.history.read to build a timeline. Use location.visits.read. You get "arrived at the gym 9:15, left 10:40", which is what a timeline shows.
• Polling current-place every thirty seconds. Register a rule. Polling burns your budget and still tells you late.

Scopes that involve places

Five scopes ask about the user's named places: location.place.current, location.place.presence, location.visits.read, location.lookup.place and location.rules.place.

For these, the user also picks which places you may ask about. They can change that later without re-minting your token, so your visible set can shrink between two calls.

Design for a user who shares nothing. current-place will answer no_place every time, and that is a valid setup, not an error.

Scopes can narrow later

Review never quietly trims your list. An application is approved as submitted or declined with reasons, and you resubmit once you've made the changes — so what you asked for is what you get, or you're told why not.

The set can still shrink after that. Your effective scopes are the intersection of your app's declared list and each user's grant, a user can narrow what they share at any time, and we can cut an app's declared scopes as an enforcement action against abuse. Both apply to live tokens immediately, so a call that worked yesterday can return 403 today.

Handle 403 by turning the feature off, not by retrying.

Full list