> ## 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.

# Session API: Sign In and Manage Your Session

> REST endpoints to issue CSRF tokens, authenticate with email and password, retrieve the current user, and sign out of a Springwinter browser session.

The Session API manages browser-based authentication for the Springwinter dashboard. It issues session cookies, provides CSRF protection for mutating requests, and lets you inspect or destroy the current session. For programmatic or CI access, use an API token with an `Authorization: Bearer` header instead — session cookies are designed for interactive browser use and are not convenient for scripts. See the [API Tokens reference](/api-reference/api-tokens) for details.

## Get a CSRF Token

**GET /api/csrf**

Issue a new CSRF token for the current session. Include the returned value as an `X-CSRF-Token` header on every subsequent POST, PATCH, PUT, or DELETE request that uses cookie-based authentication.

<CodeGroup>
  ```bash Request theme={null}
  curl https://springwinter.dev/api/csrf \
    -H "Cookie: session=<your_session_cookie>"
  ```

  ```json Response theme={null}
  {
    "token": "v2.csrf.eyJhbGciOiJIUzI1NiJ9..."
  }
  ```
</CodeGroup>

<ResponseField name="token" type="string">
  A short-lived CSRF token. Pass this as the `X-CSRF-Token` request header on mutating API calls made with a session cookie.
</ResponseField>

<Note>
  If you authenticate with an `Authorization: Bearer` token instead of a session cookie, you do not need a CSRF token — it is only required for cookie-authenticated requests.
</Note>

***

## Get the Current User

**GET /api/session**

Return the account details of the currently authenticated user, including their organization.

<CodeGroup>
  ```bash Request theme={null}
  curl https://springwinter.dev/api/session \
    -H "Authorization: Bearer swt_yourtoken"
  ```

  ```json Response theme={null}
  {
    "id": "usr_11aa22bb",
    "email": "you@example.com",
    "name": "Alex Kim",
    "organization": {
      "id": "org_99zz88yy",
      "name": "Acme Corp"
    }
  }
  ```
</CodeGroup>

<ResponseField name="id" type="string">Unique identifier for the authenticated user.</ResponseField>
<ResponseField name="email" type="string">Email address associated with the account.</ResponseField>
<ResponseField name="name" type="string">Display name of the user.</ResponseField>

<ResponseField name="organization" type="object">
  The organization the user belongs to.

  <Expandable title="Organization fields">
    <ResponseField name="id" type="string">Unique organization identifier.</ResponseField>
    <ResponseField name="name" type="string">Display name of the organization.</ResponseField>
  </Expandable>
</ResponseField>

***

## Sign In

**POST /api/session**

Authenticate with an email address and password. On success, the response sets an HttpOnly session cookie that authenticates subsequent requests.

<CodeGroup>
  ```bash Request theme={null}
  curl -X POST https://springwinter.dev/api/session \
    -H "Content-Type: application/json" \
    -H "X-CSRF-Token: v2.csrf.eyJhbGciOiJIUzI1NiJ9..." \
    -c cookies.txt \
    -d '{
      "email": "you@example.com",
      "password": "supersecret"
    }'
  ```

  ```json Response (201 Created) theme={null}
  {
    "id": "usr_11aa22bb",
    "email": "you@example.com",
    "name": "Alex Kim"
  }
  ```
</CodeGroup>

<ParamField body="email" type="string" required>
  The email address registered to your Springwinter account.
</ParamField>

<ParamField body="password" type="string" required>
  Your account password. For accounts created with Google or Microsoft sign-in, use those OAuth flows instead — this endpoint accepts passwords only for email-based accounts.
</ParamField>

<Tip>
  Most integrations are easier with an API token than with session cookies. Tokens do not require CSRF headers, do not expire on browser close, and are straightforward to rotate. Create one in **Settings → API Tokens** or via the [API Tokens endpoint](/api-reference/api-tokens).
</Tip>

***

## Sign Out

**DELETE /api/session**

Destroy the current session and clear the session cookie.

<CodeGroup>
  ```bash Request theme={null}
  curl -X DELETE https://springwinter.dev/api/session \
    -H "Cookie: session=<your_session_cookie>" \
    -H "X-CSRF-Token: v2.csrf.eyJhbGciOiJIUzI1NiJ9..."
  ```

  ```json Response (200 OK) theme={null}
  {
    "message": "Signed out successfully."
  }
  ```
</CodeGroup>

<Note>
  Session cookies are `HttpOnly` — client-side JavaScript cannot read them. This prevents cross-site scripting attacks from stealing credentials, but it also means you must use the DELETE endpoint (not client-side code) to sign out programmatically.
</Note>