Skip to main content

​
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"},
)
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 / MethodTypeDescription
MixpeekAuth.onReady(callback)(fn) => voidCalled when auth is initialized
MixpeekAuth.isSignedInbooleanWhether the current user is signed in
MixpeekAuth.userobject{ id, email, name, avatar_url }
MixpeekAuth.showSignIn()() => voidOpens the Clerk sign-in modal
MixpeekAuth.showSignUp()() => voidOpens the Clerk sign-up modal
MixpeekAuth.signOut()() => voidSigns 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:
EndpointMethodDescription
/_auth/meGETReturns the current user’s profile
/_auth/usersGETLists all users for this app (requires auth)
/_auth/sdk.jsGETThe 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.apps.mixpeek.com/_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"],
    },
)
Omit clerk_allowed_providers to enable all default providers (Google, GitHub, and email/password).