Authentication

Overview

Canvas apps support built-in authentication powered by Clerk. When you enable auth, your users can sign up and sign in via Google, GitHub, or email/password — with no extra libraries or configuration on your part. The auth SDK is auto-injected into your app at runtime. You get a window.MixpeekAuth object with methods to check sign-in state, show modals, and access user profiles.

Enabling Auth

Enable Clerk authentication by updating your app’s auth_config:

from mixpeek import Mixpeek

client = Mixpeek(api_key="your-api-key")

client.apps.update(
    app_id="app_abc123",
    auth_config={"mode": "clerk"},
)

import { Mixpeek } from 'mixpeek-sdk'

const client = new Mixpeek({ apiKey: 'your-api-key' })

await client.apps.update({
  appId: 'app_abc123',
  authConfig: { mode: 'clerk' },
})

curl -X PATCH https://api.mixpeek.com/v1/apps/$APP_ID \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"auth_config": {"mode": "clerk"}}'

Setting mode to "clerk" automatically:

Injects window.__MIXPEEK__ with Clerk configuration
Loads the /_auth/sdk.js script into your app
Enforces authentication on all /api proxy requests

You do not need to install or import any auth libraries. The canvas runtime handles everything.

Using MixpeekAuth in Your App

The SDK exposes window.MixpeekAuth with the following API:

Property / Method	Type	Description
`MixpeekAuth.onReady(callback)`	`(fn) => void`	Called when auth is initialized
`MixpeekAuth.isSignedIn`	`boolean`	Whether the current user is signed in
`MixpeekAuth.user`	`object`	`{ id, email, name, avatar_url }`
`MixpeekAuth.showSignIn()`	`() => void`	Opens the Clerk sign-in modal
`MixpeekAuth.showSignUp()`	`() => void`	Opens the Clerk sign-up modal
`MixpeekAuth.signOut()`	`() => void`	Signs out and reloads the page

React Example

// src/App.jsx — auth-gated Canvas app
import { useState, useEffect } from 'react'

export default function App() {
  const [user, setUser] = useState(null)
  const [ready, setReady] = useState(false)

  useEffect(() => {
    window.MixpeekAuth.onReady(() => {
      setReady(true)
      if (window.MixpeekAuth.isSignedIn) {
        setUser(window.MixpeekAuth.user)
      }
    })
  }, [])

  if (!ready) return <p>Loading...</p>

  if (!user) {
    return (
      <div>
        <h1>Welcome</h1>
        <p>Sign in to access this app.</p>
        <button onClick={() => window.MixpeekAuth.showSignIn()}>
          Sign In
        </button>
        <button onClick={() => window.MixpeekAuth.showSignUp()}>
          Sign Up
        </button>
      </div>
    )
  }

  return (
    <div>
      <h1>Hello, {user.name}</h1>
      <p>{user.email}</p>
      <button onClick={() => window.MixpeekAuth.signOut()}>
        Sign Out
      </button>
      {/* Your app content here */}
    </div>
  )
}

Auth Endpoints

The canvas runtime exposes three auth endpoints on your app’s domain:

Endpoint	Method	Description
`/_auth/me`	GET	Returns the current user’s profile
`/_auth/users`	GET	Lists all users for this app (requires auth)
`/_auth/sdk.js`	GET	The auth SDK script (auto-loaded, but you can load it manually)

Use /_auth/me from your frontend to verify auth state on page load without relying solely on the client-side SDK.

API Access and Billing

All /api requests are authenticated with the app owner’s API key — your end-users never need their own Mixpeek credentials.

Usage is billed to the organization that owns the Canvas app
The /api proxy supports all Mixpeek API methods: retrievers, collections, documents, and marketplace
End-users interact with your app; your API key handles the backend calls transparently

Because all API usage is billed to your organization, monitor your usage in Studio to avoid unexpected costs from high-traffic apps.

User Storage

When users sign up through your app, their metadata (email, name, avatar) is stored automatically. Each app maintains its own user list, scoped independently from other apps. Access user data via the /_auth/users endpoint:

curl https://your-app.mxp.co/_auth/users \
  -H "Authorization: Bearer $API_KEY"

Response:

[
  {
    "id": "user_abc123",
    "email": "jane@example.com",
    "name": "Jane Smith",
    "avatar_url": "https://..."
  }
]

Auth Providers

By default, Clerk authentication supports:

Google — OAuth sign-in
GitHub — OAuth sign-in
Email / password — standard credentials

Configure allowed providers via auth_config.clerk_allowed_providers:

client.apps.update(
    app_id="app_abc123",
    auth_config={
        "mode": "clerk",
        "clerk_allowed_providers": ["google", "github"],
    },
)

curl -X PATCH https://api.mixpeek.com/v1/apps/$APP_ID \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "auth_config": {
      "mode": "clerk",
      "clerk_allowed_providers": ["google", "github"]
    }
  }'

Omit clerk_allowed_providers to enable all default providers (Google, GitHub, and email/password).

User Management — invite members, assign roles, remove users
Apps overview
Deploy from Code
Custom Domains

Get started

Connect your data

Extract features

Build retrievers

Enrich & organize

Integrate & operate

Resources

Overview

Enabling Auth

Using MixpeekAuth in Your App

React Example

Auth Endpoints

API Access and Billing

User Storage

Auth Providers

​Overview

​Enabling Auth

​Using MixpeekAuth in Your App

​React Example

​Auth Endpoints

​API Access and Billing

​User Storage

​Auth Providers

​Related

Overview

Enabling Auth

Using MixpeekAuth in Your App

React Example

Auth Endpoints

API Access and Billing

User Storage

Auth Providers

Related