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

# Springwinter API Authentication — Tokens and Sessions

> Authenticate Springwinter API requests with a bearer token for automation or a cookie session with CSRF token for browser-based clients.

The Springwinter API supports two authentication methods: **API bearer tokens**, which are recommended for all automation and programmatic access, and **cookie sessions with CSRF tokens**, which the browser dashboard uses internally. Choose bearer tokens for scripts, CI pipelines, and third-party integrations. Use the cookie + CSRF flow only if you are building a browser-based client that mirrors the Springwinter dashboard behaviour.

## Method 1: Bearer Token (Recommended)

Bearer tokens are long-lived credentials you generate in the Springwinter dashboard. They authenticate every request without requiring a session cookie or CSRF validation, making them the simplest and most portable option for programmatic use.

### Create a token

1. Sign in to Springwinter at [https://springwinter.dev/auth](https://springwinter.dev/auth).
2. Open **Settings → API Tokens** (see [API Tokens](/account/api-tokens)).
3. Click **New token**, give it a descriptive name, and confirm.
4. Copy the token immediately — Springwinter shows it only once and cannot reveal it again.

<Warning>
  Store your API token in a secrets manager or environment variable. Never commit it to source control or include it in client-side code.
</Warning>

### Use the token

Pass the token in the `Authorization` header on every request:

```
Authorization: Bearer YOUR_API_TOKEN
```

#### Example

```bash theme={null}
curl https://springwinter.dev/api/projects \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```

Bearer tokens bypass CSRF validation entirely, so you do not need to fetch a CSRF token when using this method.

### Revoke a token

You can revoke a token at any time from **Settings → API Tokens**, or by calling `DELETE /api/api_tokens/{id}`. Revoked tokens are rejected immediately.

***

## Method 2: Cookie Session + CSRF Token

The cookie session flow is used by the Springwinter browser dashboard. It requires two steps: establishing a session by signing in, then attaching a CSRF token to every mutating request. You can replicate this flow programmatically, but bearer tokens are simpler for most use cases.

### Step 1 — Sign in and obtain a session cookie

Send your credentials to `POST /api/session`. On success, the server sets a session cookie that you must include in all subsequent requests.

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

The `-c cookies.txt` flag tells `curl` to save the session cookie to a file so you can reuse it across requests.

### Step 2 — Fetch a CSRF token

Retrieve a CSRF token from `GET /api/csrf`. Pass the saved session cookie with `-b cookies.txt`:

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

The response returns a CSRF token value you must attach to all mutating requests.

### Step 3 — Include the CSRF token on mutating requests

Add the `X-CSRF-Token` header to every `POST`, `PATCH`, `PUT`, and `DELETE` request:

```bash theme={null}
curl -b cookies.txt -X POST https://springwinter.dev/api/projects \
  -H "Content-Type: application/json" \
  -H "X-CSRF-Token: YOUR_CSRF_TOKEN" \
  -d '{"name": "my-project"}'
```

`GET` requests do not require a CSRF token.

### Sign out

Delete the active session by calling `DELETE /api/session`. Include the session cookie and CSRF token:

```bash theme={null}
curl -b cookies.txt -X DELETE https://springwinter.dev/api/session \
  -H "X-CSRF-Token: YOUR_CSRF_TOKEN"
```

***

## Error Responses

| Status Code | Cause | Resolution |
| - | - | - |
| `401 Unauthorized` | No valid session cookie or bearer token was provided. | Add a valid `Authorization: Bearer` header or sign in to obtain a session cookie. |
| `403 Forbidden` | The CSRF token is missing or invalid (session-based requests only). | Fetch a fresh CSRF token from `GET /api/csrf` and include it as `X-CSRF-Token`. |

***

<Tip>
  Use bearer tokens for all automated and programmatic use — scripts, CI/CD pipelines, infrastructure tooling, and third-party integrations. The cookie + CSRF flow is designed for the Springwinter browser UI and is more complex to manage outside a browser context.
</Tip>