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

# Authentication

> How MESO authenticates and authorises API requests.

## Bearer tokens

Every MESO endpoint expects a Supabase Auth access token in the `Authorization`
header:

```http theme={null}
Authorization: Bearer <access_token>
```

Tokens are short-lived. Refresh them through the Supabase Auth endpoint rather
than caching them long-term.

## What the server checks

Requests pass through a shared `requireUser` helper before any capability logic
runs. It performs three checks in order:

**1. Header present**

A missing `Authorization` header returns **401** with
`{ "success": false, "error": "Missing authorization header" }`.

**2. Token resolves to a user**

An expired, malformed or revoked token returns **401** with
`{ "success": false, "error": "Unauthorized" }`.

**3. Row ownership**

Authentication is not authorisation. Each capability separately enforces that
the caller owns the rows it touches.

## Platform-level gating

Endpoints are additionally gated at the platform edge. All capability endpoints
run with JWT verification enabled, which means an unauthenticated request is
rejected before it reaches application code.

> [!WARNING]
>
> One internal endpoint — the retrieval proxy — runs without edge JWT verification
> because it exists as a CORS/HTTPS bridge. It is not part of the documented
> surface and should not be called directly.

## Sign-in-time endpoints

A small number of endpoints are called *before* a session exists — account
lookup, signup-token validation, and code redemption. These still require a
valid project JWT: the client sends the anon key as the bearer credential. This
keeps them off the open internet without demanding a session they cannot yet
have.

> [!NOTE]
>
> Account lookup deliberately confirms whether an email is registered. This is a
> known and accepted email-enumeration trade, made so the sign-in screen can branch
> to the right flow. Rate limiting is applied.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.