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

# Authentication

> How to authenticate against the Connie API — session cookies for browser clients, bearer tokens for everything else.

## TL;DR

| Caller | Auth method | How it's set |
| - | - | - |
| **Browser / first-party UI** | `cookieAuth` — a Supabase-issued JWT session cookie named `session` | Set automatically when the user signs in to [connie.ai](https://connie.ai) |
| **Chrome extension** | Bearer JWT — `Authorization: Bearer <token>` | Issued by Connie when the extension authenticates the user |
| **MCP clients & automation** | Workspace API key (`sk_…`) — `Authorization: Bearer` | Generated in **Workspace settings → API keys**; see [MCP → Workspace API key](/mcp/api-key) |
| **Webhooks / internal services** | HMAC-signed headers | Per-endpoint signature schemes (Stripe, GitHub, Linear, etc.) |

<Info>
  **API keys work for the MCP server — not (yet) for the REST endpoints documented here.** A workspace API key (`sk_…`, generated in **Workspace settings → API keys**) authenticates against the [MCP server](/mcp/api-key), where it can list and call tools. The first-party REST endpoints in these specs accept the session cookie (or the extension bearer token) only — a `sk_…` key sent to them returns `401`. A first-class personal access token (PAT) for the REST API is still on the roadmap.
</Info>

***

## Session cookie (`cookieAuth`)

This is the auth scheme declared on every API endpoint in the OpenAPI specs.

### How to obtain it

There's no public `POST /login` endpoint to call directly. The session cookie is **issued by Supabase Auth** when a user signs in through the Connie web UI.

The flow:

1. User visits [connie.ai](https://connie.ai) and signs in (email + password, OAuth, or magic link)
2. Supabase Auth issues a signed JWT
3. The JWT is set as a cookie named `session` on the `connie.ai` domain

The cookie carries standard secure attributes — `HttpOnly`, `Secure`, `SameSite=Lax` — so JavaScript can't read it directly but every API request from the same origin includes it automatically.

### Using it from a browser

If you're calling Connie's API from a logged-in browser session, **you don't need to do anything**. The cookie travels with every `fetch` automatically as long as you set `credentials: 'include'`:

```js theme={null}
const res = await fetch('https://connie.ai/api/inbox/init', {
  credentials: 'include',
});
```

### Using it from a server

If you're proxying a user's request server-side, forward their `session` cookie:

```js theme={null}
const upstream = await fetch('https://connie.ai/api/inbox/init', {
  headers: { cookie: `session=${userSession}` },
});
```

### Refresh and logout

Session refresh is handled automatically by the Supabase SSR middleware — your client doesn't need to refresh tokens manually. Sign-out happens through the Connie UI and clears the cookie.

***

## Bearer tokens (extension)

The Connie Chrome extension uses a bearer-token flow because it doesn't share a cookie jar with the web app.

```http theme={null}
GET /api/inbox/init
Authorization: Bearer <jwt>
```

Token payload:

| Field | Value |
| - | - |
| `type` | `extension` |
| `iss` (issuer) | `conigma` |
| `aud` (audience) | `conigma-extension` |
| Expiry | 30 days from issue |

Tokens are issued by Connie when the user authenticates the extension. They're not currently exposed for general programmatic use.

<Note>
  **Builders looking for API keys:** if you're calling the **MCP server or the Tools API**, use a [workspace API key](/mcp/api-key) (`sk_…`) — that's the supported, server-to-server path today. For the **first-party REST endpoints** in these specs, a PAT system is still on the roadmap; until it ships the extension token flow is the only programmatic option. Reach out at [support@connie.ai](mailto:support@connie.ai) if you have a specific integration in mind.
</Note>

***

## HMAC-signed endpoints

A handful of inbound endpoints — webhooks and internal-service callbacks — use HMAC signatures instead of session cookies. These aren't intended for user-facing API access; they're called by external services Connie has registered.

| Endpoint | Header | Used by |
| - | - | - |
| `/api/webhooks/stripe` | `Stripe-Signature` | Stripe |
| `/api/webhooks/github` | `X-Hub-Signature-256` | GitHub |
| `/api/webhooks/linear` | `Linear-Signature` | Linear |
| `/api/webhooks/slack/events` | Slack signing secret | Slack |

The Tools module's [Webhooks reference](/tools/overview#webhooks) lists every supported provider and the signature scheme each one uses. If you're sending webhooks **into** Connie, configure the matching secret in **Tools → Webhooks**.

***

## What to do when auth fails

The API returns predictable errors when auth is missing or invalid. See [Errors & rate limits](/errors) for the full status-code reference.

| Status | When you'll see it |
| - | - |
| **401 `UNAUTHORIZED`** | Missing or invalid session / token. Re-authenticate. |
| **403 `FORBIDDEN`** | Authenticated, but the user / workspace doesn't have permission for that resource. |
| **402** | Authenticated, but the workspace is out of credits — see [Billing](/billing/overview). |

Errors always carry both an HTTP status and a JSON body like `{ "error": "message", "code": "CODE" }` so you can branch on the stable `code` rather than the human-readable string.


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