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

# Authentication

> Authenticate with the Founder Sherpa API using Supabase Auth JWT tokens.

Founder Sherpa uses [Supabase Auth](https://supabase.com/docs/guides/auth) for authentication. All API requests require a valid JWT token and the project's API key.

## Required headers

Every API request must include these headers:

```bash theme={null}
Authorization: Bearer <your-access-token>
apikey: <your-project-api-key>
Content-Type: application/json
```

| Header          | Description                                  |
| --------------- | -------------------------------------------- |
| `Authorization` | Bearer token obtained from the sign-in flow  |
| `apikey`        | Your Supabase project's anonymous key        |
| `Content-Type`  | Always `application/json` for request bodies |

## Obtaining an access token

Sign in with email and password to receive an access token:

```bash theme={null}
curl -X POST 'https://<project-ref>.supabase.co/auth/v1/token?grant_type=password' \
  -H 'apikey: <your-api-key>' \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "user@example.com",
    "password": "your-password"
  }'
```

The response includes:

```json theme={null}
{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "bearer",
  "expires_in": 3600,
  "refresh_token": "v1.MDE3YjM2..."
}
```

Use the `access_token` as your Bearer token for subsequent requests.

## Token refresh

Access tokens expire after 1 hour. Use the refresh token to get a new access token without re-entering credentials:

```bash theme={null}
curl -X POST 'https://<project-ref>.supabase.co/auth/v1/token?grant_type=refresh_token' \
  -H 'apikey: <your-api-key>' \
  -H 'Content-Type: application/json' \
  -d '{
    "refresh_token": "v1.MDE3YjM2..."
  }'
```

<Tip>
  The Founder Sherpa web app handles token refresh automatically. If you're building a custom integration, implement automatic refresh before the token expires.
</Tip>

## Multi-tenant authorization

Founder Sherpa is multi-tenant — all data is scoped to workspaces. Your access token carries your user identity, and **Row Level Security (RLS)** policies ensure you can only access data in workspaces where you're a member.

You don't need to pass a workspace ID in headers. RLS policies automatically filter data based on your workspace memberships.

## Error responses

| Status             | Meaning                                                                                        |
| ------------------ | ---------------------------------------------------------------------------------------------- |
| `401 Unauthorized` | Missing or invalid access token. Sign in again or refresh your token.                          |
| `403 Forbidden`    | Valid token but insufficient permissions (e.g., accessing a workspace you're not a member of). |
| `400 Bad Request`  | Invalid request body or parameters.                                                            |

Example error response:

```json theme={null}
{
  "error": "invalid_grant",
  "error_description": "Invalid login credentials"
}
```

## Security best practices

* **Never expose your service role key** in client-side code. The `apikey` (anonymous key) is safe for client use.
* **Store tokens securely** — use HTTP-only cookies or secure storage, not localStorage.
* **Implement token refresh** — don't require users to re-authenticate when tokens expire.
* **Use HTTPS** for all API requests.