The Auth Endpoint

Part of setting up the client-side YSweetProvider is providing it with an endpoint it can use to authorize a user to access a given document. The reason for this design is that it allows the YSweetProvider to fetch a new client token behind the scenes when the old one expires so that the application doesn’t have to intervene or ask the user to refresh the page.

The YSweetProvider’s authEndpoint value can be configured either as a string or a function that returns a ClientToken. We’ll cover both approaches below.

Configuring the `authEndpoint` with a `string`

When configuring the YSweetProvider’s authEndpoint with a string, you will need to implement the endpoint following a few rules:

The endpoint should handle POST requests
The body of the request will contain the document’s ID. E.g., { "docId": "my-doc-id-123" }
The endpoint should perform its own check to confirm the user is authorized to access the given document
The endpoint should call getOrCreateDocAndToken() to create a client token that gives the client access to the document
The endpoint should return the resulting client token as the body of the response.

When using React with Server Actions, you can pass a server action as the YDocProvider’s authEndpoint prop.

  npm add @y-sweet/sdk

App.tsx

  import { DocumentManager } from '@y-sweet/sdk'
  import { YDocProvider } from '@y-sweet/react'
 
  const manager = new DocumentManager(process.env.CONNECTION_STRING)
 
  export function App() {
    const docId = 'my-doc-id'
 
    async function getClientToken() {
      'use server'
      // In a production app, this is where you'd authenticate the user
      // and check that they are authorized to access the doc.
      return await manager.getOrCreateDocAndToken(docId)
    }
 
    return (
      <YDocProvider docId={docId} authEndpoint={getClientToken}>
        <MyCollaborativeApp />
      </YDocProvider>
    )
  }

To implement the auth endpoint using a NextJS Route Handler, create a route that matches the endpoint you provided as the authEndpoint prop. In our example, that’s app/api/auth/route.ts. The endpoint must accept a POST request, create a client token using the docId provided in the body of the request, and return the client token as the body of the response.

  npm add @y-sweet/sdk

app/api/auth/route.ts

  import { DocumentManager } from '@y-sweet/sdk'
  import { NextResponse } from 'next/server'
 
  const manager = new DocumentManager(process.env.CONNECTION_STRING)
 
  export async function POST(request: Request) {
    // In a production app, this is where you'd authenticate the user
    // and check that they are authorized to access the doc.
    const { docId } = await request.json()
    const clientToken = await manager.getOrCreateDocAndToken(docId)
    return NextResponse.json(clientToken)
  }

To implement the auth endpoint using Hono, add a route that accepts a POST request, creates a client token using the docId provided in the body of the request, and returns the client token as the body of the response.

  npm add @y-sweet/sdk

  import { DocumentManager } from '@y-sweet/sdk'
  import { Hono } from 'hono'
  import { cors } from 'hono/cors'
  import { serve } from '@hono/node-server'
 
  const docManager = new DocumentManager(process.env.CONNECTION_STRING)
 
  const app = new Hono()
  app.use('/api/auth', cors())
  app.post('/api/auth', async (c) => {
    const body = await c.req.json()
    const docId = body.docId
    // At this point, in a production app, you'd want to authenticate the user
    // and make sure they have access to the given doc
    const clientToken = await docManager.getOrCreateDocAndToken(docId)
    return c.json(clientToken)
  })
  serve(app)

To implement the auth endpoint using ExpressJS, add a route that accepts a POST request, creates a client token using the docId provided in the body of the request, and returns the client token as the body of the response.

  npm add @y-sweet/sdk

  import express from 'express'
  import cors from 'cors'
  import { DocumentManager } from '@y-sweet/sdk'
 
  const app = express()
  app.use(cors())
  app.use(express.json())
 
  const manager = new DocumentManager(process.env.CONNECTION_STRING)
 
  app.post('/api/auth', async (req, res) => {
    const docId = req.body?.docId ?? null
    // In a production app, this is where you'd authenticate the user
    // and check that they are authorized to access the doc.
    const clientToken = await manager.getOrCreateDocAndToken(docId)
    res.send(clientToken)
  })
 
  app.listen(8080)

The YSweetProvider can then be configured with a string referencing the endpoint’s URL:

my-app.ts

import { createYjsProvider } from '@y-sweet/client'
 
const doc = new Y.Doc()
const docId = 'my-doc-id'
await createYjsProvider(doc, docId, '/api/auth')

Or, if you are using @y-sweet/react, you can configure the <YDocProvider> component:

my-app.tsx

import { YDocProvider } from '@y-sweet/react'
 
const docId = 'my-doc-id'
 
<YDocProvider docId={docId} authEndpoint="/api/auth">
  <MyCollaborativeApp />
</YDocProvider>

Configuring the `authEndpoint` with a function

When configuring the YSweetProvider’s authEndpoint with a function, you still need to hit an endpoint you’ve implemented on the server that performs an auth check and creates a client token using the @y-sweet/sdk library’s getOrCreateDocAndToken(). But you have more flexibility in how you do the auth check. This approach is useful if you need to make the fetch request yourself (to add custom auth headers, or provide the doc ID in a different way, etc). Here’s an example of using a function as the authEndpoint value:

my-app.ts

import { createYjsProvider } from '@y-sweet/client'
 
const doc = new Y.Doc()
const docId = 'my-doc-id'
await createYjsProvider(doc, docId, async () => {
  const response = await fetch(`/api/auth?docId=${docId}`, {
    headers: { Authorization: `Bearer ${myCustomAuth}` }
  })
  return await response.json()
})

Connection String Running Y-Sweet locally

The Auth Endpoint

Configuring the authEndpoint with a string

Configuring the authEndpoint with a function

Configuring the `authEndpoint` with a `string`

Configuring the `authEndpoint` with a function