SynqDocs
Guides

Ask a provider for more

Choose the extra scopes a brand asks each sign-in provider for, such as a Telegram phone number or permission for your own bot to message people.

Every sign-in through a provider asks for Synq's minimum: who the person is, and their name, email or picture where the provider has them. A brand can ask for more, scope by scope, from each provider's reviewed list: Provider scopes lists them all, and GET /v1/provider-scopes serves the same list with no credential. Synq's minimum is always asked for first and can't be taken away.

Anything off a provider's list is refused with scope_not_allowed. A scope on the list whose status is coming is refused with scope_unavailable: what it grants needs Synq to read it at sign-in, or is any use only with people's provider tokens (Keep provider tokens), and Synq hasn't reviewed it for that yet. Asking people for access nobody can use is what providers' app reviews refuse, so Synq doesn't ask for it. Today Telegram's phone and telegram:bot_access can be asked for.

Setting them

An org sets a default for every brand that keeps none of its own, and a brand can replace it:

  • For the org: PUT /v1/orgs/{org}/sign-in-providers/{provider}/scopes, with org.connections.edit.
  • For one brand: PUT /v1/orgs/{org}/brands/{brand}/sign-in-providers/{provider}/scopes, with org.brands.edit.

Each takes the whole list, as { "scopes": [...] }, and replaces the one before. A brand's list replaces the org's entirely: a brand with an empty list asks for nothing extra, whatever the org's says. Clearing a brand's own goes back to the org's. Each change is recorded as brand.updated or org.updated, naming sign_in_providers.<provider>.scopes. In the dashboard, it's Ask Telegram for more (or any provider) under the brand's sign-in methods.

The brand's sign-in providers show each provider's scopes: Synq's minimum, the brand's extra and whose they are (source: brand, org or null), what a sign-in asked now, and any inactive scope that is kept but not asked for, with its reason.

Scopes that need your own app

Most extra scopes ride only on your own app at the provider (your own apps at the providers), never Synq's shared one: the provider reviews the app that asks for them, bills it, or records the grant against it. Such a scope is refused with scope_needs_own_app where sign-ins go through Synq's app. An org's own list needs the org's own app; a brand's needs the brand's own app or the org's. At GitHub it needs an OAuth App, declared with app_type: oauth_app when you set it: a GitHub App ignores scopes.

Adding a scope that needs your own app wants a plan with auth.byo_connections, as bringing the app does (plan_feature_unavailable otherwise). Keeping or taking scopes away never does, so an org that moved down keeps what it had, and a brand can save part of the list it takes from its org.

If the app goes away, nothing is deleted and no sign-in fails: the scopes it carried are inactive, with the reason scope_needs_own_app, and sign-ins leave them out. A list saved later that still names them keeps them, though they can't be added anew without the app. Bring the app back and they're asked for again.

What people see

The provider's button on the brand's sign-in page, and when someone adds the provider to their account, says what else it asks for, in the words Provider scopes lists. On Synq's shared app, the provider's own screen names Synq rather than your brand, so Synq shows a page first that says what your brand gets, with one button on. On your own app, the provider's screen names you, and there's no page of Synq's.

What was granted

People can say no to a scope at the provider, and some providers never say. At every sign-in, the person's identity keeps:

  • scopes: the extra scopes the provider says they granted.
  • unconfirmed_scopes: the extra scopes asked for that the provider never confirms either way.

A scope the provider says was declined is in neither. Both are in a user's details and in the linked_accounts claim an app or API asks for, beside what the provider said of the account. A phone number or Telegram user id goes in an API's access tokens only when they're for the brand's own app, never an agent's or another company's (linked accounts).

Telegram: your own bot messages people

Telegram's telegram:bot_access lets your own bot send a person direct messages after they sign in, without them opening the bot first. Say a community app has its own Telegram bot and wants to welcome each new member:

  1. Give Synq your bot as the brand's own Telegram app (your own apps at the providers), and add the brand's redirect URI to the bot's Allowed URLs in BotFather. Keep the bot's sign-in signing on RS256 or ES256: Telegram refuses the profile and phone scopes for EdDSA and ES256K.
  2. Set the brand's Telegram scopes to ["telegram:bot_access"], with phone too if you want the phone number on their Telegram account.
  3. When someone signs in, read their Telegram linked account: telegram_user_id is the id your bot messages them at. It isn't the account's subject, which is another identifier.
  4. From your server, call Telegram's Bot API with your bot's own token: sendMessage with chat_id set to telegram_user_id.

Telegram never says whether the person allowed bot access, so it stays in unconfirmed_scopes: your bot finds out from its first message. phone counts as granted when Telegram sends the number, as phone_number. Its phone_number_verified is Telegram's own word where Telegram sends one, and true otherwise, since Telegram documents the phone scope as the person's verified phone number: Synq doesn't check the number itself. On Synq's shared bot you can ask for phone, but not bot access, which would let Synq's bot message people rather than yours.

Telegram's older Login Widget asked for the same permission as request_access=write: on Telegram's sign-in today it's this scope.

Other providers

  • Google: its sensitive scopes need your own app verified by Google, which in Synq needs the brand on its own custom domain. Synq never asks Google to carry over grants from earlier sign-ins.
  • Microsoft: a work or school directory may require its admin to approve your app first. Someone from such a directory sees a page saying their organization must approve it. Some permissions are for work or school accounts only.
  • X: every call made with these is billed to your app's developer account.
  • Matrica: turn the same scopes on in your app's settings at Matrica too.

On this page