Instant on the Backend

You can use Instant on the server as well! This can be especially useful for running scripts, custom auth flows, or sensitive application logic.

Admin SDK

We currently offer a javascript library @instantdb/admin for using Instant in a non-browser context. This library is similar to our client SDK with a few tweaks.

init

import { init, tx, id } from '@instantdb/admin'

const db = init({
  appId: 'my-instant-app-id',
  adminToken: process.env.INSTANT_APP_ADMIN_TOKEN,
})

Similar to @instantdb/react, you must init before doing any queries or writes. Running init authenticates you against our admin API. In addition to providing your appId, you must also provide your adminToken.

Reading and Writing Data

query and transact let you read and write data as an admin.

query

const data = await db.query({ books: {}, users: {} })
const { books, users } = data

In react we export useQuery to enable "live queries", queries that will automatically update when data changes.

In the admin SDK we instead export an async query function that simply fires a query once and returns a result.

transact

const today = format(new Date(), 'MM-dd-yyyy');
const res  = await db.transact([
  tx.logs[id()].update({ date: today })
])
console.log("New log entry made for" today, "with tx-id", res["tx-id"])

transact is an async function that behaviors nearly identical to transact from @instantdb/react. It returns a tx-id on success.

Impersonating users

When you use the admin SDK, you can make any query or transaction. As an admin, you bypass permissions. But, sometimes you want to make queries on behalf of your users, and would like to respect permissions.

You can do this with the asUser function.

// Scope by their email
const scopedDb = db.asUser({ email: 'cooluser@myapp.com' })
// Or with their auth token
const token = db.auth.createToken('cooluser@myapp.com')
const scopedDb = db.asUser({ token })
// Or use the db as a guest!
const scopedDb = db.asUser({ guest: true })
// Queries and transactions will run with those permissions
await scopedDb.query({ logs: {} })

Custom Auth

You can use the Admin SDK to create your own authentication flows. You'd typically make a change on both your backend and frontend:

Backend: auth.createToken

On the backend, auth.createToken lets you create users and generate login tokens for them.

If you had an endpoint, here's how that could look:

app.post('/custom_sign_in', async (req, res) => {
  // ... your custom flow for users
  const token = await db.auth.createToken(email)
  return res.status(200).send({ token })
})

If a user with this email does not exist, auth.createToken will create a user for you.

Frontend: auth.signInWithToken

Once you generate the token, you can pass it along to your frontend and sign in with auth.signInWithToken:

const auth = init(/* ... */)

async function handleSignIn() {
  // Get the token from your backend
  const token = await fetch('/signin', ...);
  // Sign in
  auth.signInWithToken(token);
}

Custom Endpoints

Sometimes you'll want to write custom endpoints in your backend. You can use the admin SDK to authenticate users on those endpoints.

Backend: auth.verifyToken

In your endpoint, you can expect to receive token. You can then use auth.verifyToken to get the associated user. For example:

app.post('/custom_endpoint', async (req, res) => {
  // verify the token this user passed in
  const user = await db.auth.verifyToken(req.headers['token'])
  if (!user) {
    return res.status(400).send('Uh oh, you are not authenticated')
  }
  // ...
})

Frontend: user.refresh_token

In your frontend, the user object has a refresh_token property. You can pass this token on to your endpoint:

const db = init(/* ... */)

function App() {
  const { user } = db.useAuth();
  // call your api with `user.refresh_token`
  function onClick() {
    myAPI.customEndpoint(user.refresh_token, ...);
  }
}

More SDKs to come

In the future we will expose an HTTP API so you can use Instant with your language of choice. Stay tuned!