SynqDocs
Guides

Accounts your app verifies

Link the accounts your own service proves, such as your Telegram bot or your game's server, and send people sign-in links from it.

Some accounts only your own service can vouch for: the Telegram user who just messaged your bot, the player on your game server. A provider your app verifies turns them into linked accounts on a person's Synq account. Your service proves who someone is there, Synq records it, and the person confirms it in your app before anything links.

Say Acme Guild's Telegram bot sends members event reminders. A member taps "Link Telegram" in the Acme Guild app, the app opens t.me/acmeguildbot?start=<code>, the bot hands the code to Acme Guild's server, and the app asks "Link Telegram @ada?". From then on the bot knows which member it is talking to, and, where Acme Guild turns sign-in links on, its "Open the event" button signs them in to the app.

Adding one

Every plan has them. A brand's own OpenID Connect and OAuth 2.0 providers are on Scale and up.

{ "id": "custom-acme-telegram", "name": "Telegram", "sign_in_tickets": false }
  • Its id is custom- and a slug you pick, unique among the brand's own providers of every kind, and never changes: it is the provider's name on people's linked accounts and in your server's requests.
  • Use for: linking alone (sign_in_tickets: false, the default), or linking and sign-in links (true). Turning sign-in links on wants a sign-in from the last 5 minutes for a person; an API key never does.
  • Off until you turn it on: POST …/enable. Turned off, no code is made or redeemed, nothing pending is confirmed and every sign-in link stops working at once. Linked accounts stay.

It is never a way to sign in on the brand's pages, and never counts as one: removing someone's other ways in is refused as before, whatever they linked here. Each change is recorded as brand.updated.

Linking, from the app

The person starts in your app, signed in. With @synqauth/react:

import { useAppLink } from '@synqauth/react'

function LinkTelegram() {
  const telegram = useAppLink('custom-acme-telegram')
  if (telegram.status === 'pending') {
    return (
      <p>
        Link {telegram.pending!.provider_name} @{telegram.pending!.handle}?
        <button onClick={() => void telegram.confirm()}>Confirm</button>
        <button onClick={() => void telegram.reject()}>Not me</button>
      </p>
    )
  }
  if (telegram.status === 'linked') return <p>Telegram linked.</p>
  return (
    <button
      onClick={async () => {
        const { data } = await telegram.start()
        if (data) window.open(`https://t.me/acmeguildbot?start=${data.code}`)
      }}
    >
      Link Telegram
    </button>
  )
}

start() asks the account API for a link code (POST /me/v1/link-codes), and the hook watches for your server to redeem it, at once when the person comes back to the page. status is waiting, then pending with the account your server named, then linked or rejected, or expired when time ran out. With @synqauth/js, the same steps are accounts.app.start(provider), accounts.app.pending(), accounts.app.confirm(identity) and accounts.app.reject(identity).

A link code is a credential:

  • 256 random bits, kept by Synq only as a hash, single use, for 10 minutes;
  • bound to the person, the brand, the provider and the session of the app that made it: only that session sees what it became, and only it confirms it, so another device, or another app, never can.

Where the provider makes sign-in links, the account becomes a way to sign in through them, so making a code wants a sign-in Synq proved within the brand's link_reauth_window (at least the last 5 minutes), and the person is emailed once it links.

Redeeming, on your server

When your service learns who opened its link (your bot got /start <code> from Telegram's user 987654321), your server redeems the code with an org API key that has org.users.identities.edit: POST /v1/orgs/{org}/brands/{brand}/link-codes/redeem.

{
  "code": "Oyewzb7tB0AL3anJsAjr7DTSO3Ojr34HOqKwZ611DYM",
  "provider": "custom-acme-telegram",
  "subject": "987654321",
  "handle": "ada",
  "name": "Ada Lovelace"
}
  • The code goes in the body, never the URL: request paths reach logs.
  • subject says who the person is at your service for life: it must never change or be reused for someone else.
  • A code that is unknown, expired, used, or made for another provider is link_code_invalid; an account someone has linked already is identity_in_use, and leaves the code unspent.
  • Only from a server: a person's token, or a request from a browser, is server_only.

The answer names the pending identity and the person who made the code. Until they confirm it in the app, within 10 minutes, it links nothing, signs nobody in and gets no sign-in link: tell them to go back to the app.

A person your server already knows

When your server knows who someone is already, it adds the account at once, confirmed, with POST …/users/{user}/identities and the same fields as a redemption. The person's account page shows it as added by your brand (added_by: "server"), and they can remove it.

Where the provider's sign_in_tickets is on, your server makes a link that signs in a person who confirmed an account there: POST /v1/orgs/{org}/brands/{brand}/sign-in-tickets, with an org API key that has org.users.signInTickets.create.

{
  "provider": "custom-acme-telegram",
  "subject": "987654321",
  "client_id": "app_01h455vb4pex5vsknk084sn02q",
  "return_to": "https://app.acme-guild.example/api/auth/callback"
}

It answers { url, expires_at }: send url to the person, as your bot's button. Add &returnTo=/events/42 to it for where they land in your app.

  • For one app, and one of its redirect URIs: client_id is one of the brand's own apps, and return_to one of its redirect URIs exactly as registered.
  • Once, for 2 minutes, kept only as a hash, for a confirmed account only.
  • Never spent by a GET: the link opens your app's route mount, whose page has a button; the button posts it, and your server pushes it to Synq in a pushed authorization request (synq_ticket, with prompt=login). A link preview or a scanner that only fetches the link spends nothing, and the link still works for the person afterwards. @synqauth/nextjs does all of it at its callback.
  • Never a fresh sign-in: the sign-in is amr: ["ticket"], and it can't add or remove ways to sign in, delete the account or make API keys. Those want the person to sign in another way first.
  • Recorded: in the person's sign-ins, and in the audit log as user.sign_in_ticket_created and user.sign_in_ticket_used.
  • Turned off at once: turning the provider off, or its sign-in links, refuses every link, those made already included.

A server without @synqauth/nextjs does the same: when its callback gets synq_ticket without a code, it shows a page whose button posts the ticket back to it, and on that post it sends a pushed authorization request with synq_ticket, prompt=login and its own PKCE, then the browser to Synq with the request_uri. Two of the page's headers decide whether the button gets through: a Content-Security-Policy's form-action names your issuer beside 'self', since browsers hold the redirect after a form's post to it too, and a Referrer-Policy of no-referrer makes the post say Origin: null, so a server that checks where a post came from turns it away (strict-origin keeps the ticket out of every Referer and lets the origin through).

With your agent

Synq's MCP server reads these providers (get_configuration's app_verified_providers) and adds, changes, turns on or off, or deletes one through request_configuration_change: at once, unless you or your org asked to approve every AI agent change (Approving every change). Redeeming codes, adding accounts and making sign-in links are your server's, with an org API key: they vouch for who someone is, and a link signs them in, so no agent does them.

On this page