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

# Authenticate with the Swisstools API

> Learn how session cookies and API key bearer tokens work, and how to send authenticated requests to the Swisstools API.

The Swisstools API uses two authentication mechanisms. The web dashboard uses session-based cookie auth, set automatically when you sign in. Project-scoped API keys authenticate programmatic access. Most management endpoints accept **either** a session cookie or an API key; the Feature Flags SDK endpoint requires an API key.

## Session Authentication (Cookie)

When you sign in through the Swisstools dashboard — via email/password or GitHub/Google OAuth — the server sets a session cookie in your browser automatically. All management API endpoints (`/api/teams`, `/api/projects`, `/api/projects/:projectId/mocks`, etc.) require this session cookie to be present on every request.

If you're calling these endpoints programmatically (for example, from a script or CI pipeline), sign in first via `POST /api/auth/sign-in` and include the returned `Set-Cookie` value in all subsequent requests.

**Sign in and capture the session cookie:**

```bash theme={null}
curl -c cookies.txt -X POST https://swisstools.dev/api/auth/sign-in/email \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "password": "your-password"}'
```

**Use the session cookie in subsequent requests:**

```bash theme={null}
curl -b cookies.txt https://swisstools.dev/api/teams
```

## API Key Authentication (Bearer Token)

Project API keys are required by the **Feature Flags SDK endpoint** (`GET /api/flags/:recordId`) and are also accepted on every other project-scoped endpoint (`/api/projects/:projectId/…`) as an alternative to a session cookie — keys are project-admin equivalent. Pass the key as a bearer token in the `Authorization` header, or via the `x-api-key` header.

```bash theme={null}
curl https://swisstools.dev/api/flags/org-0ujsswThIGTUYm2K8FjOOfXtY1K \
  -H "Authorization: Bearer fk_2a9bX1c0d3e4f5g6h7i8j9k0"
```

**How to create an API key:**

1. Open your project in the Swisstools dashboard.
2. Navigate to **Feature Flags → API Keys**.
3. Click **Create** and give the key a name.
4. Copy the key immediately — it is only shown once.

<Note>
  The API key is scoped to the project it was created in. The SDK endpoint validates that the record you're requesting belongs to the same project as the key.
</Note>

## Unauthenticated Requests

Auth failures return `401`/`403`/`404` with an `error` message. The exact wording depends on the route:

* Project-scoped endpoints, no session and no key → `401 {"error": "Unauthorized"}`.
* Project-scoped endpoints, a bad/expired/revoked key → `401 {"error": "Invalid or expired API key"}`.
* SDK route (`/api/flags/:recordId`), no key → `401 {"error": "Missing API key"}`; bad key → `401 {"error": "Invalid or revoked API key"}`.
* A key (or session) for a different project → `403 {"error": "API key does not have access to this project"}`.
* A session lacking the required team role → `403 {"error": "Requires admin role on this project"}`.
* An unknown project reference → `404 {"error": "Project not found"}`.

<Note>
  Mock invocation URLs (`https://<team_ref>-<project_slug>.swisstools.dev/api/mock/<endpoint>`) and webhook inbox URLs (`https://<team_ref>-<project_slug>.swisstools.dev/api/webhook/<webhook_id>`) are **public** — no authentication is required to call them. This is intentional so that external services and clients can reach them without credentials.
</Note>