> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mixpeek.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Add Clerk-based sign-in to your Canvas app with zero configuration. Users authenticate via Google, GitHub, or email — the SDK is auto-injected.

## 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`:

<CodeGroup>
  ```python Python theme={null}
  from mixpeek import Mixpeek

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

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

  ```javascript JavaScript theme={null}
  import { Mixpeek } from 'mixpeek-sdk'

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

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

  ```bash cURL theme={null}
  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"}}'
  ```
</CodeGroup>

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

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

***

## 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

```jsx theme={null}
// 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) |

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

***

## 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

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

***

## 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:

```bash theme={null}
curl https://your-app.mxp.co/_auth/users \
  -H "Authorization: Bearer $API_KEY"
```

Response:

```json theme={null}
[
  {
    "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`:

<CodeGroup>
  ```python Python theme={null}
  client.apps.update(
      app_id="app_abc123",
      auth_config={
          "mode": "clerk",
          "clerk_allowed_providers": ["google", "github"],
      },
  )
  ```

  ```bash cURL theme={null}
  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"]
      }
    }'
  ```
</CodeGroup>

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

***

## Related

* [User Management](/canvas/apps/users) — invite members, assign roles, remove users
* [Apps overview](/canvas/apps)
* [Deploy from Code](/canvas/apps/deploy)
* [Custom Domains](/canvas/apps/domains)