Authentication & tokens

dropin never sees a password or an OAuth flow: your backend is the identity provider. It signs a short-lived HS256 JWT locally with your tenant’s api_secret — zero network calls to dropin to mint one — and hands that token to the client. apiSecret must never reach the browser; only @dropinnodex/server (Node-only) can use it.

Mint a user token (server only)

server

// server-only — never bundle this into a browser build
import { DropInServer } from '@dropinnodex/server'

const server = new DropInServer({
  tenantId: process.env.DROPIN_TENANT_ID!,
  apiKey: process.env.DROPIN_API_KEY!,
  apiSecret: process.env.DROPIN_SIGNING_SECRET!,
  url: 'https://api.getnodex.cloud',
})

// Inside your own token endpoint, after you've authenticated the caller yourself:
const token = await server.createUserToken(userId, { expiresIn: '1h' }) // max 24h

expiresIn accepts "30s", "15m", "1h", "1d"-style strings and is capped at 24 hours — a longer value throws before a token the gateway would reject is even minted.

There’s no client- or react-side equivalent: minting requires apiSecret, which only ever lives on your server.

Keep your server’s clock accurate

Tokens are stamped with your server’s clock. If that clock is more than 60 seconds fast, every token you mint is rejected with UNAUTHENTICATED — the gateway will not accept a token that claims to have been issued in the future, because such a token would also survive revokeUserTokens.

A slow clock is harmless. If you see unexplained UNAUTHENTICATED responses, compare your server’s time against the Date header on any API response. Any NTP-synced host is fine; this generally only bites unmanaged VMs and machines resumed from suspend.

Construct a client with a tokenProvider

The client (and the React provider wrapping it) never holds apiSecret — only a tokenProvider callback that fetches a token from your own backend endpoint. tokenProvider is called once on init and again on a 401, not per request (spec §9).

client

import { DropInClient } from '@dropinnodex/client'

const client = new DropInClient({
  url: 'https://api.getnodex.cloud',
  apiKey: process.env.NEXT_PUBLIC_DROPIN_API_KEY!,
  tokenProvider: async () => {
    const res = await fetch('/api/token')
    const { token } = await res.json()
    return token
  },
})

react

import { DropInProvider } from '@dropinnodex/react'

function Providers({ children, userId }: { children: React.ReactNode; userId: string }) {
  return (
    <DropInProvider
      url={process.env.NEXT_PUBLIC_DROPIN_API_URL!}
      apiKey={process.env.NEXT_PUBLIC_DROPIN_API_KEY!}
      userId={userId}                        // who the tokenProvider mints for
      tokenProvider={async () => {
        const res = await fetch('/api/token')
        return (await res.json()).token as string
      }}
    >
      {children}
    </DropInProvider>
  )
}

Pass userId if a user can change without a remount

The client is memoized, and it caches its token until a 401 — so on a user switch inside a mounted provider, neither a new tokenProvider closure nor a re-render dislodges the still-valid token minted for whoever was signed in before. The next user reads the previous user’s feed, with their own_reactions and their notification scope, and nothing errors.

userId is the input that breaks the memo: change it and the client is rebuilt, the cached pages are dropped, and every mounted hook re-seeds to empty and shows a loading state rather than painting the previous user’s rows while the refetch flies. Sign-in flows that remount the provider, and apps with one session for the page’s life, need nothing — but passing it costs nothing either.

One thing userId cannot fix for you: initialData is not re-fetched on a switch. An SSR-prefetched page is minted for whoever was signed in when the server rendered it, so the hook honours it only for the identity it mounted under and ignores it afterwards. If your app server-renders per user, re-render with that user’s page; the feed reads correctly either way, it just loses the no-flash hydration until you do.

DropInProvider also accepts an already-constructed client directly: <DropInProvider client={myClient}> — useful if you need to build the DropInClient yourself (e.g. to share it outside React).

Revoke a user’s tokens

Tokens are signed offline, so there is nothing to “delete” — a token stays valid until it expires. Revocation is how you cut one short: it is recorded server-side and enforced from the next request onward, so a token already sitting in a browser stops working immediately.

server

await server.revokeUserTokens(userId)

Call this on logout, on a ban, or when an account is compromised. It invalidates all of that user’s outstanding tokens, not one specific token.

This is also why the 24h TTL ceiling is an upper bound rather than a recommendation: short tokens shrink the window in which a leaked one is useful, and revocation covers the rest.

Related

• Limits — token TTL ceiling and the per-tenant rate limits every authenticated request charges.
• Data security — what we store, where, and why we never hold your users’ credentials.
• Server SDK reference — every option on DropInServer, generated from the typings.