SynqDocs
Management APISign-in providers

Set a brand's extra scopes at a sign-in provider

What the brand's sign-ins and links ask the provider for beyond Synq's minimum, which is always asked for first: the whole list, replacing the org's there entirely (an empty list asks for nothing extra at this brand). Each scope it adds must be on the provider's list at `GET /v1/provider-scopes` and `available` (422 `scope_not_allowed` or `scope_unavailable`); one that needs your own app needs the brand's own app or the org's there (422 `scope_needs_own_app`; at GitHub, an OAuth App), and adding one wants a plan with `auth.byo_connections` (403 `plan_feature_unavailable`). A scope the brand asks for already, its own or its org's, stays even where it can't be sent now, listed in `inactive`; keeping or taking scopes away never needs the plan. The hosted pages say what each asks for in plain words, and what the person granted is on their identity and in `linked_accounts`. Needs `org.brands.edit`. Recorded as `brand.updated`, naming `sign_in_providers.<provider>.scopes`.

PUT/v1/orgs/{org}/brands/{brand}/sign-in-providers/{provider}/scopes

What the brand's sign-ins and links ask the provider for beyond Synq's minimum, which is always asked for first: the whole list, replacing the org's there entirely (an empty list asks for nothing extra at this brand). Each scope it adds must be on the provider's list at GET /v1/provider-scopes and available (422 scope_not_allowed or scope_unavailable); one that needs your own app needs the brand's own app or the org's there (422 scope_needs_own_app; at GitHub, an OAuth App), and adding one wants a plan with auth.byo_connections (403 plan_feature_unavailable). A scope the brand asks for already, its own or its org's, stays even where it can't be sent now, listed in inactive; keeping or taking scopes away never needs the plan. The hosted pages say what each asks for in plain words, and what the person granted is on their identity and in linked_accounts. Needs org.brands.edit. Recorded as brand.updated, naming sign_in_providers.<provider>.scopes.

Authorization

bearer
AuthorizationBearer <token>

An org API key (sk_live_…, sk_test_…), or an access token from the Synq issuer (the synq brand, on the accounts host) for this API.

In: header

Path Parameters

org*string

The org's id

Match^org_[0-9a-hjkmnp-tv-z]{26}$
brand*string

The brand's id

Match^brd_[0-9a-hjkmnp-tv-z]{26}$
provider*string

The sign-in provider

Value in

  • "google"
  • "github"
  • "microsoft"
  • "apple"
  • "facebook"
  • "x"
  • "discord"
  • "telegram"
  • "matrica"

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

curl -X PUT "https://api.synq.build/v1/orgs/org_01h455vb4pex5vsknk084sn02q/brands/brd_01h455vb4pex5vsknk084sn02q/sign-in-providers/google/scopes" \  -H "Authorization: Bearer $SYNQ_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "scopes": [      "phone",      "telegram:bot_access"    ]  }'
{  "provider": "google",  "link_by_email": true,  "hosted_domain": "acme.example",  "microsoft_tenant": "organizations",  "use": "sign_in",  "keep_tokens": true,  "kept_claims": [    "locale"  ],  "app": {    "client_id": "app_01h455vb4pex5vsknk084sn02q",    "app_type": "oauth_app",    "redirect_uri": "https://acme.auth.synq.build/federation/google/callback",    "updated_at": "2026-10-21T12:00:00.000Z"  },  "signs_in_through": "brand",  "redirect_uri": "https://acme.auth.synq.build/federation/google/callback",  "offered": true,  "synq_app": true,  "scopes": {    "minimum": [      "openid",      "profile"    ],    "extra": [      "phone",      "telegram:bot_access"    ],    "source": "org",    "asked": [      "openid",      "profile",      "phone",      "telegram:bot_access"    ],    "inactive": [      {        "scope": "telegram:bot_access",        "reason": "scope_needs_own_app"      }    ]  }}

Set a brand’s own app at a sign-in provider PUT

The app is the brand’s own, which wins over the org’s. The app at the provider must register `redirect_uri` exactly: the brand’s own callback, on its issuer’s host. Checks the client id and secret with the provider first (a token request it refuses for the code, not the app, when it takes them), then keeps them in place of any before. Microsoft's needs Entra's `auth_time` optional claim turned on, or a fresh sign-in through it is refused. Apple takes no `client_secret`: send its Services ID as `client_id` with `team_id`, `key_id` and the `.p8` `private_key`, from which Synq signs each client secret it sends Apple. Apple delivers mail to private relay addresses only from domains registered with the app, so register the domain Synq sends your brands' email from (the domain of their sender address) under Sign in with Apple for Email Communication, or Synq's email to people who hid their address bounces. Every other provider takes `client_id` and `client_secret`. Recorded as `org.updated` (or `brand.updated`) with the client id, never the secret. 422 `connection_rejected` when the provider refuses the app; 503 when it can't be reached; at most 10 a minute per org (429). Needs `org.connections.edit`, and a plan with `auth.byo_connections` (403 `plan_feature_unavailable` otherwise, naming the plan in `required_plan`); forgetting one never does. A person needs a sign-in at Synq from the last 5 minutes whose time Synq proved (send them to sign in with `max_age=300`), else 403 `fresh_sign_in_required`; an API key never does.

Set the org’s own app at a sign-in provider PUT

The app is the org’s, for every brand without its own. The app at the provider must register every one of `redirect_uris` exactly: each live brand’s own callback, on its issuer’s host. A brand made later adds its own, which the answer that makes it names. Checks the client id and secret with the provider first (a token request it refuses for the code, not the app, when it takes them), then keeps them in place of any before. Microsoft's needs Entra's `auth_time` optional claim turned on, or a fresh sign-in through it is refused. Apple takes no `client_secret`: send its Services ID as `client_id` with `team_id`, `key_id` and the `.p8` `private_key`, from which Synq signs each client secret it sends Apple. Apple delivers mail to private relay addresses only from domains registered with the app, so register the domain Synq sends your brands' email from (the domain of their sender address) under Sign in with Apple for Email Communication, or Synq's email to people who hid their address bounces. Every other provider takes `client_id` and `client_secret`. Recorded as `org.updated` (or `brand.updated`) with the client id, never the secret. 422 `connection_rejected` when the provider refuses the app; 503 when it can't be reached; at most 10 a minute per org (429). Needs `org.connections.edit`, and a plan with `auth.byo_connections` (403 `plan_feature_unavailable` otherwise, naming the plan in `required_plan`); forgetting one never does. A person needs a sign-in at Synq from the last 5 minutes whose time Synq proved (send them to sign in with `max_age=300`), else 403 `fresh_sign_in_required`; an API key never does.