# Synq

> Synq is the auth platform for Solana-ecosystem and web3-adjacent apps. It ships OIDC + brand-scoped identity, a hosted IdP, and first-party SDKs for web, React, Next.js, React Native, and Solana Mobile. This file follows the llms.txt convention so AI coding agents can fetch the canonical doc index in one request.

Production issuer: `https://api.synq.id`
Hosted dashboard: `https://app.synq.id`
Docs root: `https://docs.synq.id`

## Quick choice — which SDK do I install?

- **Vanilla JS / Vue / Svelte / non-React web** → `@synqid/js`
- **React (Vite, CRA, Remix)** → `@synqid/react` + `@synqid/js`
- **Next.js (App Router or Pages)** → `@synqid/nextjs` + `@synqid/js`
- **React Native (Expo or bare)** → `@synqid/react-native` + `@synqid/js`
- **Solana Mobile dApp (MWA)** → `@synqid/solana-mobile` + `@synqid/react-native`

All public SDKs live under the `@synqid` npm scope. Internal IdP-direct SDKs are `@synqid/internal-*` and not for third-party use.

## Canonical doc pages

- [Quickstart](https://docs.synq.id/quickstart)
- [Concepts: identity model](https://docs.synq.id/concepts/identity-model)
- [Concepts: orgs & brands](https://docs.synq.id/concepts/orgs-and-brands)
- [Concepts: sessions & tokens](https://docs.synq.id/concepts/sessions-and-tokens)
- [Concepts: scopes & consent](https://docs.synq.id/concepts/scopes-and-consent)
- [Concepts: providers](https://docs.synq.id/concepts/providers)
- [Concepts: security](https://docs.synq.id/concepts/security)
- [Concepts: BYO credentials](https://docs.synq.id/concepts/byo-credentials)
- [Concepts: webhooks](https://docs.synq.id/concepts/webhooks)
- [Concepts: audit log](https://docs.synq.id/concepts/audit-log)
- [Concepts: token gates](https://docs.synq.id/concepts/token-gates)

## SDK docs

- [@synqid/js](https://docs.synq.id/sdks/js)
- [@synqid/react](https://docs.synq.id/sdks/react)
- [@synqid/nextjs](https://docs.synq.id/sdks/nextjs)
- [@synqid/react-native](https://docs.synq.id/sdks/react-native)
- [@synqid/solana-mobile](https://docs.synq.id/sdks/solana-mobile)

## Guides

- [Production checklist](https://docs.synq.id/guides/production-checklist)
- [Multi-environment](https://docs.synq.id/guides/multi-environment)
- [Build a Solana Mobile app](https://docs.synq.id/guides/build-a-solana-mobile-app)
- [Migrating from Clerk](https://docs.synq.id/guides/migrating/clerk)
- [Migrating from NextAuth](https://docs.synq.id/guides/migrating/nextauth)
- [Migrating from WorkOS](https://docs.synq.id/guides/migrating/workos)
- [Rotate everything](https://docs.synq.id/guides/rotate-everything)

## API reference

- [OIDC endpoints](https://docs.synq.id/api-reference/oidc)
- [Users](https://docs.synq.id/api-reference/users)
- [Orgs](https://docs.synq.id/api-reference/orgs)
- [Brands](https://docs.synq.id/api-reference/brands)
- [Token gates](https://docs.synq.id/api-reference/token-gates)
- [Webhooks](https://docs.synq.id/api-reference/webhooks)
- [Audit log](https://docs.synq.id/api-reference/audit-log)

## Reference

- [Error codes](https://docs.synq.id/reference/errors)
- [JWT claims](https://docs.synq.id/reference/jwt-claims)
- [Webhook events](https://docs.synq.id/reference/webhook-events)
- [Permissions](https://docs.synq.id/reference/permissions)
- [Glossary](https://docs.synq.id/reference/glossary)

## Drop-in snippets agents can copy verbatim

### React (Vite / CRA / Remix)

```tsx
// main.tsx
import { SynqProvider } from '@synqid/react'
import { SignIn, Connect } from '@synqid/react/ui'

export default function Root({ children }) {
  return (
    <SynqProvider
      issuer="https://api.synq.id"
      clientId={import.meta.env.VITE_SYNQ_CLIENT_ID}
      redirectUri={`${window.location.origin}/auth/callback`}
      theme="dark"            // or "light" | "glass" | "monochrome" | "brutalist"
      colorScheme="system"
    >
      {children}
      <SignIn />              // mount once; opens via requestSignIn()
      <Connect />             // mount once; opens via requestConnect()
    </SynqProvider>
  )
}
```

```tsx
// Anywhere inside the tree
import { useSynq, useUser } from '@synqid/react'

function MyButton() {
  const user = useUser()
  const { requestSignIn, signOut } = useSynq()
  if (!user) return <button onClick={() => requestSignIn()}>Sign in</button>
  return <button onClick={signOut}>Sign out {user.firstName}</button>
}
```

### Next.js App Router

```ts
// app/api/auth/[...synq]/route.ts
import { synqHandlers } from '@synqid/nextjs/server'
export const { GET, POST } = synqHandlers()
```

```ts
// any RSC
import { auth } from '@synqid/nextjs/server'

export default async function Page() {
  const session = await auth()
  if (!session) return <a href="/api/auth/signin">Sign in</a>
  return <p>Hi {session.user.firstName}</p>
}
```

### React Native (Expo)

```tsx
// App.tsx
import { SynqProvider, SignInSheet, ConnectSheet } from '@synqid/react-native'
import { BottomSheetModalProvider } from '@gorhom/bottom-sheet'

export default function App() {
  return (
    <BottomSheetModalProvider>
      <SynqProvider
        issuer="https://api.synq.id"
        clientId={process.env.EXPO_PUBLIC_SYNQ_CLIENT_ID!}
        redirectUri="myapp://oauth/callback"
        uiTheme="dark"
        colorScheme="system"
      >
        <Root />
        <SignInSheet />
        <ConnectSheet />
      </SynqProvider>
    </BottomSheetModalProvider>
  )
}
```

## Theme tokens (web + native)

All five built-in presets share the same token names so a designer's
spec carries one-to-one between `@synqid/react` (CSS values) and
`@synqid/react-native` (RN-native values).

Token groups: `primary*`, `surface*`, `border*`, `text*`, `danger`,
`success`, `warning`, `backdrop`, font-family triplet,
`fontWeightHeadline`/`Button`, spacing scale `Xs..Xl`, radii scale
`Sm..Lg/Full`, and web-only `shadow*`/`glow`/`backdropBlur`/`duration*`/
`easingStandard`. See the [@synqid/react](https://docs.synq.id/sdks/react)
and [@synqid/react-native](https://docs.synq.id/sdks/react-native) pages
for the full table.

## Error codes (most common)

| Code | Where | Meaning |
|---|---|---|
| `access_denied` | `signInError` | User denied consent at the provider |
| `invalid_grant` | OIDC token endpoint | Refresh token expired or revoked — force a re-login |
| `invalid_client` | OIDC token endpoint | `clientId` / `clientSecret` mismatch |
| `mismatched_redirect_uri` | OIDC auth endpoint | `redirectUri` does not match the App registration |
| `pkce_required` | OIDC auth endpoint | `code_challenge` missing — public clients must use PKCE |
| `consent_required` | OIDC silent flow | The user must complete an interactive flow |
| `wallet_signature_invalid` | Solana sign-in | SIWS payload was tampered with or the wallet rejected |
| `token_gate_failed` | Brand-scoped sign-in | The org's token gate rejected the wallet — see token-gate page |

Full catalog: https://docs.synq.id/reference/errors

## Operating notes for agents

- The `issuer` URL is always `https://api.synq.id` for the hosted IdP. Do not invent regional variants.
- All clientId values are stable across environments unless the user is on a dedicated tenant — assume one ID per Synq App.
- Mobile redirect URIs **must** be deep links (scheme like `myapp://...`). Universal links are not supported on RN yet.
- For Next.js, server-only env vars (`SYNQ_CLIENT_SECRET`) belong in `.env.local`, never `NEXT_PUBLIC_*`.
- Synq is *not* a wallet provider. The Solana provider (`signIn({ provider: 'solana' })`) signs a SIWS payload using whatever wallet adapter the consumer wires up.